@greatwait/api-client

The typed JavaScript client for Greatwait, generated from the service's public contracts.

Greatwait is a scheduling service for reliable HTTPS callbacks. You give it a callback and a time; it makes the call, retries what it must, and records what happened so you can read the outcome.

Invited alpha. This package publishes on the alpha dist-tag and has no latest. Install it explicitly, and pin the exact version in anything you care about.

npm install @greatwait/api-client@alpha @greatwait/contracts@alpha

First value in nine calls

The complete journey — verify your credential, create a destination, create an idempotent one-shot, prove the retry is safe, and read the delivery attempt against your own receiver — is a runnable program rather than a fragment. It lives in the repository at docs/quickstarts/javascript.md, and the machine-readable version of the same sequence ships in @greatwait/contracts as generated/v1/first-value-journey.json.

You need three things this package cannot get for you: a project, an API credential, and an HTTPS receiver you control. The first two are created by a signed-in person in the dashboard, because the operations that create them accept only a session. The third is yours because Greatwait does not send your payload to a receiver somebody else owns.

Calling an operation

import { createGreatwaitClient } from "@greatwait/api-client";
import { responseSchemaFor } from "@greatwait/contracts";

const greatwait = createGreatwaitClient({
  baseUrl: process.env.GREATWAIT_API_URL,
  credential: process.env.GREATWAIT_API_KEY,
  fetch,
});

const created = await greatwait.request("schedules_create", {
  delaySeconds: 30,
  endpoint: process.env.GREATWAIT_ENDPOINTID,
});

const schedule = responseSchemaFor("schedules.create").parse(created);

request returns the unparsed body and responseSchemaFor gives you the contract's own schema for that operation, so the shape is never declared twice. requestDetailed returns the response headers an operation publishes as well — which is how you read the ETag you need for a conditional write, and the Idempotency-Replayed marker that tells you a retry did not create anything.

fetch is an option rather than a global, so the same code runs on Node, in a Cloudflare Worker, and in a browser.

Refusals

Every refusal arrives as a GreatwaitClientError carrying the service's RFC 9457 problem document. Branch on problem.code, which is stable, rather than on the prose or the bare status.

import { GreatwaitClientError } from "@greatwait/api-client";

try {
  await greatwait.request("schedules_create", body, {
    "Idempotency-Key": key,
  });
} catch (error) {
  if (error instanceof GreatwaitClientError) {
    console.error(error.problem?.code, error.problem?.detail);
    // Surfaced, never acted on: whether a retry is safe depends on whether you
    // sent an idempotency key, which is your decision and not this client's.
    if (error.retryable) {
      /* back off and try again */
    }
  }
}

The client does not retry, does not back off, and has no timeout of its own. Those are the caller's, and a client that made them for you would make the one decision it cannot make correctly — whether repeating your request is safe.

Receiving callbacks

Each callback is signed over the exact request bytes with the per-endpoint secret that endpoints.create returned once. Verify before parsing.

import { createNodeCallbackMiddleware } from "@greatwait/api-client/callback-middleware";

createCallbackVerifier is the primitive if you are not on Node; createCallbackReceiver and createFetchCallbackHandler cover a Worker. All of them read the exact bytes, verify, and only then parse — the order matters, and getting it the other way round is the defect the middleware exists to prevent.

Credentials

The credential has exactly one home: GreatwaitClientOptions.credential, sent as an Authorization header. It is never logged and never placed in a URL. Keep it in the environment or in protected configuration; do not pass it as a command-line argument, where any other user on the machine can read it.

Compatibility

• Node 22.13 or newer, and any runtime with fetch and Web Crypto.
• ESM only.
• The contract version this client is generated against is published as CONTRACT_VERSION in @greatwait/contracts. It is dated and moves independently of any deployment.

MIT licensed. Issues: https://github.com/flowxo/greatwait/issues.