Using the SDK

Creating a client

DimeSchedulerClient is the single entry point. The constructor takes an options object:

import DimeSchedulerClient, { Environment } from "@dimescheduler/sdk";

const client = new DimeSchedulerClient({ apiKey: "MY_API_KEY" });

// Sandbox
const sandbox = new DimeSchedulerClient({
    apiKey: "MY_API_KEY",
    environment: Environment.Sandbox,
});

The default environment is production. The Environment enum is a string enum where each value is the base URL, so you can pass any URL to point at a mock or a self-hosted instance:

const local = new DimeSchedulerClient({
    apiKey: "test",
    environment: "http://127.0.0.1:4010" as Environment,
});

Re-use a single client across your app - it owns a fetch instance and a retry policy.

Domain accessors

Every entity hangs off a typed accessor on the client. Names mirror the .NET and Python SDKs 1:1, in idiomatic camelCase:

client.categories         // /category
client.appointments       // /appointment
client.jobs               // /job
client.tasks              // /task
client.resources          // /resource
client.filterGroups       // /filterGroup
client.filterValues       // /filterValue
client.messages           // /message
client.notifications     // /notification

CRUD-shaped entities expose create, update, delete, and getAll. Write methods accept either a single object or an array:

await client.categories.create(category);
await client.categories.create([cat1, cat2, cat3]);
await client.categories.update(category);
await client.categories.delete(category);
const { data } = await client.categories.getAll();

Endpoints with their own shape get purpose-built methods:

await client.appointments.get(startDate, endDate, ["R1", "R2"]);
await client.notifications.get(1, 50, { sort: "createdAt:desc" });
await client.messages.send({ text: "Heads up!", severity: "Warning" });
await client.geocoding.geocodeText("221B Baker Street", "GB");
await client.optimization.fieldService(request);

For the full accessor list, see client.ts.

Models and types

Body and response types live under @dimescheduler/sdk/models. Write entities (Category, Resource, Appointment) match POST/PUT bodies; read DTOs (CategoryDto, ResourceDto) match GET responses:

import type { Category, CategoryDto } from "@dimescheduler/sdk/models";

For schemas without a re-export, every type is reachable via the generated components["schemas"] map exported from the package root:

import type { components } from "@dimescheduler/sdk";
type StoredProcedureData = components["schemas"]["Models.StoredProcedureData"];

Results

Every call returns { data, error, response } - the same shape as openapi-fetch, which the SDK is built on:

const { data, error, response } = await client.categories.getAll();

response.ok       // boolean - HTTP 2xx
response.status   // status code
data              // typed body on success
error             // typed error body on failure

The SDK never throws on a non-2xx - branch on response.ok (or error) and decide how to react:

const { data, error } = await client.categories.create(category);
if (error) {
    logger.warn("Create failed", error);
    return;
}

Retries

Transient failures retry by default - network errors and HTTP 408 / 429 / 500 / 502 / 503 / 504. Backoff is exponential with jitter and honours Retry-After.

Override the policy via retry:

const client = new DimeSchedulerClient({
    apiKey: "MY_API_KEY",
    retry: { maxRetries: 5, initialDelayMs: 1000, maxDelayMs: 60000 },
});

Pass retry: false to disable retries entirely.

Middleware

The client is built on openapi-fetch, so you can intercept requests and responses:

client.use({
    onRequest({ request }) {
        request.headers.set("X-Trace-Id", crypto.randomUUID());
    },
    onResponse({ response }) {
        metrics.observe(response.status);
    },
});

Use client.eject(middleware) to remove a middleware.

Custom fetch

For runtimes that don't ship fetch, or when you want to plug in a wrapped fetch (instrumentation, retries, edge runtime helpers), pass fetch:

import nodeFetch from "node-fetch";

const client = new DimeSchedulerClient({
    apiKey: "MY_API_KEY",
    fetch: nodeFetch as unknown as typeof fetch,
});