@dukkan.one/app-sdk

Decodes base64url with or without padding.

The consent URL a merchant is sent to (docs/apps/authorization#authorize).

base64url without padding, as PKCE and state values are encoded.

Lowercase hex encoding.

Canonical JSON exactly as the platform hashes request bodies (packages/contracts/vectors/canonical-json.json): keys sorted at every depth, arrays in order, no whitespace. Useful to detect, client-side, that two payloads would collide on one key.

Whether an app may PATCH an order from from to to (the server stays authoritative).

Collects every item; use only when the total is known to be small.

AES-256-GCM sealer with zero-downtime key rotation: seal with the current key, open with current then previous. Keys are 32 bytes, base64. The wire format (iv.tag.ciphertext, each base64) matches the first-party apps' lib/crypto.mjs, so migrating an existing token table needs no rewrite.

Creates a typed Platform API client for one install. Reads are retried on 429 and 5xx; writes carry an Idempotency-Key; a rejected access token is refreshed once through the token store's lock.

Token store over a key-value backend. Token rows are sealed before they reach the backend; the refresh lock is a short lease taken with putIfAbsent and polled by waiters.

Deterministic key from your own entity identity, so a crashed process that re-runs the same job sends the same key and gets the recorded result instead of a second refund: deterministicIdempotencyKey("refund", orderId, jobId). Namespaced and hashed, so the parts can be any length and never leak.

Turns a failed response into the most specific error the SDK knows. The body is the documented envelope when the platform produced it; anything else (a proxy page, an empty body) still yields a usable error.

Redeems the authorization code from the callback for the first token pair. The response carries install_id, store_id and store_slug; key your storage on the ids.

PKCE S256 (RFC 7636); pinned by packages/contracts/vectors/pkce.json.

A random state value (16 bytes, base64url) to bind the callback to the request that started it.

Decodes hex; returns null for odd length or non-hex input instead of throwing.

HMAC-SHA256 as lowercase hex: the webhook signature primitive.

Constant-time HMAC check: WebCrypto's verify compares inside the runtime, so the comparison never leaks through timing in JavaScript land.

Walks a cursor-paginated list one item at a time, fetching the next page only when the current one is exhausted.

Walks cursor pages. Two guards stop a misbehaving server from producing an endless loop: a cursor that repeats, and a hard page ceiling.

Parses the query the platform appends to redirect_uri. A consent denial or a platform-side refusal arrives as error (with state echoed).

The S256 challenge for a verifier: base64url(sha256(verifier)).

Cryptographically random bytes from WebCrypto.

Random key for a write that has no natural identity (reused across the SDK's own retries).

A random UUID v4.

Deep-redacts a value for logging: strings are scrubbed, keys that name a secret are replaced wholesale, and Pii-marked fields are dropped.

Replaces every platform token or secret in a string (dk_app_at_…, dk_whsec_…, …) with a redacted marker; every SDK error message passes through it.

Presents a refresh token for a new pair. Rotation is single-use: presenting the same token twice revokes the install (a 30 second leeway covers a race between two instances). Prefer TokenManager, which serialises refreshes through your store's lock.

sha256 of the canonical JSON of a payload: the value the platform compares when the same key arrives with a different body.

SHA-256 as lowercase hex.

Constant-time equality for equal-length byte strings (lengths differ → false, fast).

Builds the StoredTokens row from a token response, computing accessExpiresAt from expires_in and keeping the previous store id and scopes when the response omits them.

Reads a Pii-branded value where a plain string is needed (a message body, a rendered template). Keep the brand everywhere else so PII never reaches a log by accident.

A non-2xx answer from the Platform API, already parsed into the documented envelope.

401 from the API. invalid_token means refresh and retry (the SDK does that once); the other two mean the merchant changed something and the app must send them back through consent.

Typed Platform API client for one install. Every method throws a typed DukkanError on failure; reads paginate through async iterators; writes attach an Idempotency-Key (random, or derived from your own reference) and report whether the platform replayed a recorded result.

The app's own configuration (options, dukkan.app.toml) is unusable.

409 of any kind; subclasses narrow the ones the SDK can name. code is the specific platform code when there is one (insufficient_stock, variant_unavailable, payment_method_disabled), else conflict, and details.lines is typed for insufficient_stock (nothing was written).

Base of every error the SDK throws; code is stable for programmatic handling.

The network or the runtime failed before a response existed (timeouts included).

An OAuth error body ({ error }) from the authorize or token endpoint.

429 with the server's Retry-After already parsed.

The install has no usable tokens: the refresh token was revoked, reuse was detected, or the store removed the app. Send the merchant through consent again; every API call for this install throws this until then.

422: the body was well-formed JSON but fails the contract (a missing shipping_address for delivery, a discount above the lines, a currency the store does not sell in: currency_not_allowed). details.fields lists the paths; fix the payload, never retry unchanged.

A delivery the receiver refused; reason maps to the small JSON error body it answered.

409: the same Idempotency-Key was used with a different payload, or is still in progress.

409: the order's status matrix has no edge for the requested transition.

Single-process store for tests, CLIs and scripts. The lock is a per-install promise chain, which is exactly what one process needs and nothing a second process could rely on: never use this behind more than one instance.

403: the install no longer holds a scope this call (or topic) needs.

Hands out a valid access token for one install.

Refresh discipline (ADR 0012): one refresh at a time per install in this process (single flight), and one at a time across processes through the store's lock. Inside the lock the row is re-read: if a sibling already rotated, its pair is used and no request is made. An invalid_grant gets one more re-read (the platform answers it for a race it detected within its 30 s leeway). If the row still holds the same refresh token, the lock is released, the manager waits past the leeway, and presents the token once more: a sibling that really rotated has saved by then, while a thief who rotated our token is caught by the platform's reuse detection, which revokes the whole family instead of leaving the stolen pair alive. Only then is the install marked reconnect-required.

details of a 409 as the SDK types it: lines is present for insufficient_stock, every other key passes through.

Configuration of createDukkanClient: the install, the token store and credentials, the platform origin, and optional fetch, timeout, retry and logging hooks.

A minimal logger the SDK writes to; every line passes through redaction.

How a write chooses its Idempotency-Key: an explicit key, or parts that identify the write in your own system.

One short line of an insufficient_stock conflict: what was asked for and what the store can sell.

The smallest surface a key-value backend needs (Cloudflare KV, Redis, Deno KV, Upstash...). putIfAbsent is what makes the refresh lock real across instances; without it the adapter falls back to an in-process mutex and says so at construction.

Your app's client id and secret. The secret may be a function so a rotated value is read at call time.

A cursor page as every list endpoint returns it.

A PKCE verifier and its S256 challenge.

The JSON body every Platform API error carries: a machine code, a message, the request id and optional details.

Retry policy for Platform API calls (ADR 0012, App SDK plan):

• Reads (GET/HEAD/DELETE) always retry on 429 and transient 5xx.
• Writes retry ONLY when the request carries an Idempotency-Key, which the client attaches to every write, so a retry can never double-apply.
• Retry-After is honoured up to a cap; beyond it the error surfaces.
• Full-jitter exponential backoff otherwise, three attempts in total.
• 401 is never retried here; the transport refreshes once and re-issues.

Envelope encryption for tokens at rest (AES-256-GCM helper shipped in ./sealer).

What an app persists per install. Tokens are stored by the app (encrypted at rest through a SecretSealer), never by the SDK: the SDK only reads, refreshes and writes back through the TokenStore contract.

What /apps/oauth/token returns on both grants (identity fields since 2026-09-09).

Persistence contract every app implements once (adapters for Postgres and key-value stores ship with the SDK).

withRefreshLock is the important one: the platform revokes an install when a rotated refresh token is presented again (theft detection), so two instances must never refresh the same install concurrently. The lock serialises refreshes across processes; the SDK re-reads inside it and skips the refresh when a sibling already rotated.

details of a 422: fields names every rejected path.

One field the platform rejected in a 422, with the JSON path and the reason.

Options every write accepts: how to choose its Idempotency-Key.

What a write returns: the data, whether the platform replayed a recorded response, the key that was sent, and the request id.

GET /products filters; ids is a list here and joined with commas on the wire (at most 100).

Machine codes a 409 from POST /orders carries besides the generic conflict.

Brand for customer-contact fields (the DPA-gated clients:read scope). The type is a plain string at runtime; the brand keeps PII from flowing into places typed for ordinary strings (log lines, analytics, third-party calls) without an explicit unwrapPii.

Machine codes the Platform API puts in error.code (docs/reference/api#errors).

products.search: q is required, the other filters are optional.

Scopes that unlock customer contact PII; the portal lets only DPA-accepted developers request them.

Every scope an app can request, in the platform's canonical order.

Where the merchant platform lives; every OAuth and API path hangs off it.

Idempotency-Key helpers (docs/reference/api#idempotency). The platform remembers a key for 24 hours per install: the same key with the same body replays the recorded response, the same key with a different body is a 409.

A sealer that stores plaintext. Only for tests and throwaway tools; production stores use createAesGcmSealer or their own.

Accepted reason values of POST /inventory/movements.

GET /products?ids= and GET /products/variants?ids= accept at most this many ids per call.

Transitions an app may request through PATCH /orders/{id}/status, per current status.

Every order status the platform reports.

Every payment_status value: a projection of the payments ledger, never set directly.

Dated v1 revision this SDK was generated against (X-Dukkan-Api-Version).

Default User-Agent of every Platform API call: dukkan-app-sdk/<version>.

The package version, injected from package.json at build time (tsup define; vitest does the same).

The statuses an app may set through PATCH /orders/{id}/status.

Read scope an install must hold to receive a topic; null for lifecycle topics.

Every topic an app can subscribe to, from x-dukkan-topic-scopes.