@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/fulfillments/index.js

@@ -0,0 +1,534 @@
+import { errorFromErrorResult, isErrorResult, NotFoundError, ValidationError, } from '@sixtyninecommerce/core';
+/** The longest override reason the engine stores. */
+export const FULFILLMENT_COVERAGE_REASON_MAX_LENGTH = 500;
+/** Every field of `OrderOverpaymentOption`. */
+const OVERPAYMENT_OPTION_FIELDS = /* GraphQL */ `
+  available
+  code
+  message
+`;
+/**
+ * Its own document, like every call here: on an engine without the query this call alone fails
+ * validation.
+ */
+export const FULFILLMENT_CANCEL_PREVIEW_QUERY = /* GraphQL */ `
+  query FulfillmentCancelPreview($fulfillmentId: ID!) {
+    fulfillmentCancelPreview(fulfillmentId: $fulfillmentId) {
+      fulfillmentId
+      overpayments {
+        orderId
+        orderCode
+        amount
+        currencyCode
+        refund { ${OVERPAYMENT_OPTION_FIELDS} }
+        accountCredit { ${OVERPAYMENT_OPTION_FIELDS} }
+      }
+    }
+  }
+`;
+/** `$overpayment` and `$idempotencyKey` are optional and left out of the variables when not given. */
+export const CANCEL_FULFILLMENT_MUTATION = /* GraphQL */ `
+  mutation CancelFulfillment(
+    $fulfillmentId: ID!
+    $overpayment: [FulfillmentCancelOverpaymentInput!]
+    $idempotencyKey: String
+  ) {
+    cancelFulfillment(
+      fulfillmentId: $fulfillmentId
+      overpayment: $overpayment
+      idempotencyKey: $idempotencyKey
+    ) {
+      fulfillment {
+        id
+        state
+      }
+      settlements {
+        orderId
+        orderCode
+        amount
+        currencyCode
+        choice
+      }
+    }
+  }
+`;
+/** Every field of `OrderFulfillmentCoverageOverride`. */
+const COVERAGE_OVERRIDE_FIELDS = /* GraphQL */ `
+  id
+  orderId
+  reason
+  actorKind
+  actorId
+  outstandingAtGrant
+  currencyCode
+  createdAt
+  active
+`;
+/** Its own document: on an engine without the query this call alone fails validation. */
+export const ORDER_FULFILLMENT_COVERAGE_QUERY = /* GraphQL */ `
+  query OrderFulfillmentCoverage($orderId: ID!) {
+    orderFulfillmentCoverage(orderId: $orderId) {
+      orderId
+      orderCode
+      currencyCode
+      policyActive
+      covered
+      outstanding
+      exempt
+      exemptReason
+      allowed
+      override { ${COVERAGE_OVERRIDE_FIELDS} }
+    }
+  }
+`;
+/** `$idempotencyKey` is optional and left out of the variables when not given. */
+export const ALLOW_UNCOVERED_FULFILLMENT_MUTATION = /* GraphQL */ `
+  mutation AllowUncoveredFulfillment($orderId: ID!, $reason: String!, $idempotencyKey: String) {
+    allowUncoveredFulfillment(orderId: $orderId, reason: $reason, idempotencyKey: $idempotencyKey) {
+      ${COVERAGE_OVERRIDE_FIELDS}
+    }
+  }
+`;
+function invalidCoverage(field, message) {
+    return new ValidationError({
+        code: 'FULFILLMENT_COVERAGE_OVERRIDE_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field, code: 'FULFILLMENT_COVERAGE_OVERRIDE_INVALID', message }],
+    });
+}
+function assertOrderId(orderId) {
+    if (typeof orderId !== 'string' || orderId.trim() === '') {
+        throw invalidCoverage('orderId', 'An order id is required.');
+    }
+}
+/** Refused before any request: the engine would refuse it the same way. */
+function assertOverrideReason(reason) {
+    const text = typeof reason === 'string' ? reason.trim() : '';
+    if (text === '') {
+        throw invalidCoverage('reason', 'Say why this order may be handed over before it is paid: a reason is required.');
+    }
+    if (text.length > FULFILLMENT_COVERAGE_REASON_MAX_LENGTH) {
+        throw invalidCoverage('reason', `The reason is at most ${FULFILLMENT_COVERAGE_REASON_MAX_LENGTH} characters.`);
+    }
+    return text;
+}
+function toCoverageOverride(raw) {
+    return {
+        id: raw.id,
+        orderId: raw.orderId,
+        reason: raw.reason,
+        actorKind: raw.actorKind,
+        actorId: raw.actorId,
+        outstandingAtGrant: raw.outstandingAtGrant,
+        currencyCode: raw.currencyCode,
+        createdAt: raw.createdAt,
+        active: raw.active,
+    };
+}
+const OVERPAYMENT_CHOICES = new Set([
+    'REFUND',
+    'ACCOUNT_CREDIT',
+]);
+function invalidCancel(field, message) {
+    return new ValidationError({
+        code: 'FULFILLMENT_CANCEL_OVERPAYMENT_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field, code: 'FULFILLMENT_CANCEL_OVERPAYMENT_INVALID', message }],
+    });
+}
+/** Refused before any request: the engine would refuse each, less legibly. */
+function assertCancelRequest(fulfillmentId, input) {
+    if (typeof fulfillmentId !== 'string' || fulfillmentId.trim() === '') {
+        throw invalidCancel('fulfillmentId', 'A fulfillment id is required.');
+    }
+    const seen = new Set();
+    for (const [index, entry] of (input.overpayment ?? []).entries()) {
+        const orderId = entry?.orderId;
+        if (typeof orderId !== 'string' || orderId.trim() === '') {
+            throw invalidCancel(`overpayment[${String(index)}].orderId`, 'Each choice names an order.');
+        }
+        if (!OVERPAYMENT_CHOICES.has(entry.choice)) {
+            throw invalidCancel(`overpayment[${String(index)}].choice`, `The choice for order ${orderId} must be REFUND or ACCOUNT_CREDIT; got ${JSON.stringify(entry.choice)}.`);
+        }
+        if (seen.has(orderId)) {
+            throw invalidCancel(`overpayment[${String(index)}].orderId`, `Order ${orderId} is named twice: give one choice per order.`);
+        }
+        seen.add(orderId);
+    }
+}
+/** An option as the SDK types it: `code` and `message` are null when it is open. */
+function toOption(raw) {
+    return { available: raw.available, code: raw.code ?? null, message: raw.message ?? null };
+}
+export const REPORT_APP_FULFILLMENT_MUTATION = /* GraphQL */ `
+  mutation ReportAppFulfillment(
+    $fulfillmentId: ID!
+    $input: ReportAppFulfillmentInput!
+    $idempotencyKey: String
+  ) {
+    reportAppFulfillment(
+      fulfillmentId: $fulfillmentId
+      input: $input
+      idempotencyKey: $idempotencyKey
+    ) {
+      id
+      state
+      trackingCode
+      method
+    }
+  }
+`;
+export const ORDER_FULFILLMENT_PARCELS_QUERY = /* GraphQL */ `
+  query OrderFulfillmentParcels($id: ID!) {
+    order(id: $id) {
+      id
+      fulfillments {
+        id
+        trackingCode
+        customFields {
+          myparcelShipmentId
+          myparcelShipmentIds
+          parcelCount
+          trackingCodes
+        }
+      }
+    }
+  }
+`;
+/** Every field of `MyparcelUnretractedShipment`, shared with the stock-transfer twin. */
+export const UNRETRACTED_SHIPMENT_FIELDS = /* GraphQL */ `
+  shipmentId
+  reference
+  verdict
+  status
+  statusName
+  billable
+  hidden
+  reason
+  cause
+  firstRecordedAt
+  lastCheckedAt
+  resolvedAt
+`;
+/**
+ * Its own document, never part of the parcel read: an engine without the
+ * field refuses this call alone, and the order card still renders.
+ */
+export const ORDER_FULFILLMENT_UNRETRACTED_SHIPMENTS_QUERY = /* GraphQL */ `
+  query OrderFulfillmentUnretractedShipments($id: ID!) {
+    order(id: $id) {
+      id
+      fulfillments {
+        id
+        myparcelUnretractedShipments { ${UNRETRACTED_SHIPMENT_FIELDS} }
+      }
+    }
+  }
+`;
+export const FULFILLMENT_PARCEL_TRACKING_QUERY = /* GraphQL */ `
+  query FulfillmentParcelTracking($id: ID!) {
+    warehouseFulfillment(id: $id) {
+      trackingCodes
+      parcelTrackingCodes
+      parcelCount
+    }
+  }
+`;
+/**
+ * Its own document on purpose: `chargedParcelCount` exists only on an engine
+ * that serves it, so on an older one this call alone fails validation and the
+ * demand the create flow reads beside it does not.
+ */
+export const WAREHOUSE_CHARGED_PARCEL_COUNT_QUERY = /* GraphQL */ `
+  query WarehouseChargedParcelCount($input: WarehouseDemandInput!) {
+    warehouseDemand(input: $input) {
+      items {
+        orderId
+        chargedParcelCount
+      }
+    }
+  }
+`;
+export const MYPARCEL_FULFILLMENT_LABEL_MUTATION = /* GraphQL */ `
+  mutation MyparcelFulfillmentLabel($fulfillmentId: ID!, $format: MyparcelLabelFormatEnum!) {
+    getMyparcelFulfillmentLabel(fulfillmentId: $fulfillmentId, format: $format) {
+      format
+      base64
+      contentType
+      filename
+    }
+  }
+`;
+/**
+ * Its own document, like every call here: on an engine without the mutation
+ * this call alone fails validation. `$format` is optional and left out of the
+ * variables when not asked for.
+ */
+export const LABEL_MYPARCEL_FULFILLMENT_PARCELS_MUTATION = /* GraphQL */ `
+  mutation LabelMyparcelFulfillmentParcels($fulfillmentId: ID!, $format: MyparcelLabelFormatEnum) {
+    labelMyparcelFulfillmentParcels(fulfillmentId: $fulfillmentId, format: $format) {
+      __typename
+      ... on MyparcelLabelParcelsQueued {
+        fulfillmentId
+        parcels
+        missing
+        queued
+      }
+      ... on ErrorResult {
+        errorCode
+        message
+      }
+    }
+  }
+`;
+/**
+ * Clears the engine's MyParcel budget: 3 × 10s attempts plus two capped waits.
+ * Every merged MyParcel label (a fulfillment's, a stock transfer's) runs the
+ * same engine download, so they share it.
+ */
+export const MYPARCEL_LABEL_TIMEOUT_MS = 55_000;
+/** The engine's entries as they are: the fields are the SDK's, one to one. */
+export function toUnretractedShipments(raw) {
+    return (raw ?? []).map((entry) => ({
+        shipmentId: entry.shipmentId,
+        reference: entry.reference ?? null,
+        verdict: entry.verdict,
+        status: entry.status ?? null,
+        statusName: entry.statusName ?? null,
+        billable: entry.billable ?? null,
+        hidden: entry.hidden,
+        reason: entry.reason,
+        cause: entry.cause,
+        firstRecordedAt: entry.firstRecordedAt,
+        lastCheckedAt: entry.lastCheckedAt,
+        resolvedAt: entry.resolvedAt ?? null,
+    }));
+}
+function orderNotFound(orderId) {
+    return new NotFoundError({
+        code: 'ORDER_NOT_FOUND',
+        message: `This store has no order ${orderId}.`,
+        status: 404,
+        service: 'vendure',
+    });
+}
+/** The stale-list rule: trust the carrier's list only while it starts with `trackingCode`. */
+function trustedTrackingCodes(list, trackingCode) {
+    const single = trackingCode?.trim() ?? '';
+    const listed = (list ?? []).filter((code) => typeof code === 'string' && code.trim() !== '');
+    if (listed.length > 0 && listed[0] === single)
+        return listed;
+    return single ? [single] : [];
+}
+/** The engine's `authoritativeShipmentIds`: the list only while it starts with the single id. */
+function trustedShipmentIds(list, single) {
+    if (typeof single !== 'number' || !Number.isInteger(single) || single <= 0)
+        return [];
+    const first = String(single);
+    return list?.[0] === first ? [...list] : [first];
+}
+/** The bytes of a base64 label document (`atob`: no Node `Buffer`, it ships to browsers). */
+export function decodeBase64(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+const LABEL_FORMATS = new Set(['A4', 'A6']);
+function invalidLabelRequest(field, message) {
+    return new ValidationError({
+        code: 'MYPARCEL_LABEL_INPUT_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+        details: [{ field, code: 'MYPARCEL_LABEL_INPUT_INVALID', message }],
+    });
+}
+/** Refused before any request: the engine would refuse both, less legibly. */
+function assertLabelRequest(fulfillmentId, format) {
+    if (typeof fulfillmentId !== 'string' || fulfillmentId.trim() === '') {
+        throw invalidLabelRequest('fulfillmentId', 'A fulfillment id is required.');
+    }
+    if (format !== undefined && !LABEL_FORMATS.has(format)) {
+        throw invalidLabelRequest('format', `format must be 'A4' or 'A6', or left out to label every parcel still missing one; got ${JSON.stringify(format)}.`);
+    }
+}
+export function createFulfillmentsModule(transport) {
+    return {
+        async parcelsOfOrder(orderId, options) {
+            const data = await transport.graphql({ api: 'admin', query: ORDER_FULFILLMENT_PARCELS_QUERY, variables: { id: orderId } }, options);
+            if (!data.order)
+                throw orderNotFound(orderId);
+            return (data.order.fulfillments ?? []).map((fulfillment) => ({
+                fulfillmentId: fulfillment.id,
+                shipmentIds: trustedShipmentIds(fulfillment.customFields?.myparcelShipmentIds, fulfillment.customFields?.myparcelShipmentId),
+                parcelCount: fulfillment.customFields?.parcelCount ?? null,
+                trackingCode: fulfillment.trackingCode ?? null,
+                trackingCodes: trustedTrackingCodes(fulfillment.customFields?.trackingCodes, fulfillment.trackingCode ?? null),
+            }));
+        },
+        async unretractedShipmentsOfOrder(orderId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ORDER_FULFILLMENT_UNRETRACTED_SHIPMENTS_QUERY,
+                variables: { id: orderId },
+            }, options);
+            if (!data.order)
+                throw orderNotFound(orderId);
+            return (data.order.fulfillments ?? []).map((fulfillment) => ({
+                fulfillmentId: fulfillment.id,
+                shipments: toUnretractedShipments(fulfillment.myparcelUnretractedShipments),
+            }));
+        },
+        async parcelTracking(fulfillmentId, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: FULFILLMENT_PARCEL_TRACKING_QUERY,
+                variables: { id: fulfillmentId },
+            }, options);
+            return data.warehouseFulfillment;
+        },
+        async chargedParcelCount(input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: WAREHOUSE_CHARGED_PARCEL_COUNT_QUERY,
+                variables: {
+                    input: {
+                        stockLocationId: input.stockLocationId,
+                        orderIds: [input.orderId],
+                        ...(input.includeIneligible ? { includeIneligible: true } : {}),
+                        ...(input.routing ? { routing: [...input.routing] } : {}),
+                        take: 1,
+                    },
+                },
+            }, options);
+            const entry = data.warehouseDemand.items.find((item) => item.orderId === input.orderId);
+            return entry?.chargedParcelCount ?? null;
+        },
+        async myparcelLabel(fulfillmentId, format, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: MYPARCEL_FULFILLMENT_LABEL_MUTATION,
+                variables: { fulfillmentId, format },
+            }, { timeoutMs: MYPARCEL_LABEL_TIMEOUT_MS, ...options });
+            const { base64, ...document } = data.getMyparcelFulfillmentLabel;
+            return { ...document, bytes: decodeBase64(base64) };
+        },
+        async labelMyparcelParcels(fulfillmentId, input = {}, options) {
+            const format = input?.format;
+            assertLabelRequest(fulfillmentId, format);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: LABEL_MYPARCEL_FULFILLMENT_PARCELS_MUTATION,
+                variables: { fulfillmentId, ...(format === undefined ? {} : { format }) },
+            }, options);
+            const result = data.labelMyparcelFulfillmentParcels;
+            if (isErrorResult(result))
+                throw errorFromErrorResult(result);
+            const queued = result;
+            return {
+                fulfillmentId: queued.fulfillmentId,
+                parcels: queued.parcels,
+                missing: queued.missing,
+                queued: queued.queued,
+            };
+        },
+        async cancelPreview(fulfillmentId, options) {
+            if (typeof fulfillmentId !== 'string' || fulfillmentId.trim() === '') {
+                throw invalidCancel('fulfillmentId', 'A fulfillment id is required.');
+            }
+            const data = await transport.graphql({ api: 'admin', query: FULFILLMENT_CANCEL_PREVIEW_QUERY, variables: { fulfillmentId } }, options);
+            const preview = data.fulfillmentCancelPreview;
+            return {
+                fulfillmentId: preview.fulfillmentId,
+                overpayments: preview.overpayments.map((entry) => ({
+                    orderId: entry.orderId,
+                    orderCode: entry.orderCode,
+                    amount: entry.amount,
+                    currencyCode: entry.currencyCode,
+                    refund: toOption(entry.refund),
+                    accountCredit: toOption(entry.accountCredit),
+                })),
+            };
+        },
+        async cancel(fulfillmentId, input = {}, options) {
+            assertCancelRequest(fulfillmentId, input);
+            const overpayment = input.overpayment ?? [];
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CANCEL_FULFILLMENT_MUTATION,
+                // A variable, not a header: the Admin API takes the key as an argument.
+                variables: {
+                    fulfillmentId,
+                    ...(overpayment.length > 0
+                        ? { overpayment: overpayment.map(({ orderId, choice }) => ({ orderId, choice })) }
+                        : {}),
+                    ...(options?.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                },
+            }, options);
+            const result = data.cancelFulfillment;
+            return {
+                fulfillment: { id: result.fulfillment.id, state: result.fulfillment.state },
+                settlements: result.settlements.map((entry) => ({
+                    orderId: entry.orderId,
+                    orderCode: entry.orderCode,
+                    amount: entry.amount,
+                    currencyCode: entry.currencyCode,
+                    choice: entry.choice,
+                })),
+            };
+        },
+        async coverage(orderId, options) {
+            assertOrderId(orderId);
+            const data = await transport.graphql({ api: 'admin', query: ORDER_FULFILLMENT_COVERAGE_QUERY, variables: { orderId } }, options);
+            const coverage = data.orderFulfillmentCoverage;
+            return {
+                orderId: coverage.orderId,
+                orderCode: coverage.orderCode,
+                currencyCode: coverage.currencyCode,
+                policyActive: coverage.policyActive,
+                covered: coverage.covered,
+                outstanding: coverage.outstanding,
+                exempt: coverage.exempt,
+                exemptReason: coverage.exemptReason ?? null,
+                allowed: coverage.allowed,
+                override: coverage.override ? toCoverageOverride(coverage.override) : null,
+            };
+        },
+        async allowUncovered(orderId, reason, options) {
+            assertOrderId(orderId);
+            const text = assertOverrideReason(reason);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: ALLOW_UNCOVERED_FULFILLMENT_MUTATION,
+                // A variable, not a header: the Admin API takes the key as an argument.
+                variables: {
+                    orderId,
+                    reason: text,
+                    ...(options?.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                },
+            }, options);
+            return toCoverageOverride(data.allowUncoveredFulfillment);
+        },
+        async reportAppFulfillment(fulfillmentId, input, options) {
+            const data = await transport.graphql({
+                api: 'admin',
+                query: REPORT_APP_FULFILLMENT_MUTATION,
+                // A variable, not a header: the Admin API takes the key as an argument.
+                variables: {
+                    fulfillmentId,
+                    input,
+                    ...(options?.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                },
+            }, options);
+            const reported = data.reportAppFulfillment;
+            // Core stores "no tracking code" as an empty string.
+            return { ...reported, trackingCode: reported.trackingCode || null };
+        },
+    };
+}

package/dist/heads/index.d.ts

@@ -83,6 +83,64 @@ export declare const CREATE_MUTATION = "\n  mutation CreateChannelHead($input: C
 export declare const UPDATE_MUTATION = "\n  mutation UpdateChannelHead($id: ID!, $input: UpdateChannelHeadInput!) {\n    updateChannelHead(id: $id, input: $input) { \n  id\n  channelId\n  installationId\n  key\n  kind\n  name\n  origins\n  deepLinkBase\n  deepLinkScheme\n  defaultOrderScope\n  eventSubscriptionId\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
 export declare const DELETE_MUTATION = "\n  mutation DeleteChannelHead($id: ID!) {\n    deleteChannelHead(id: $id)\n  }\n";
 export declare const SET_DEFAULT_MUTATION = "\n  mutation SetDefaultChannelHead($id: ID!) {\n    setDefaultChannelHead(id: $id) { \n  id\n  channelId\n  installationId\n  key\n  kind\n  name\n  origins\n  deepLinkBase\n  deepLinkScheme\n  defaultOrderScope\n  eventSubscriptionId\n  isDefault\n  createdAt\n  updatedAt\n }\n  }\n";
+/**
+ * A head's PRIVATE STOREFRONT TOKEN (`s69p_`, spec §6.3, §15.21) — never the
+ * token itself, which {@link HeadPrivateTokensModule.issue} returns once.
+ */
+export interface HeadStorefrontToken {
+    id: string;
+    headId: string;
+    name: string;
+    /** `s69p_<lookup id>` — enough to recognise the token in a list, never to use it. */
+    prefix: string;
+    createdAt: string;
+    /** When a service last verified it, to within about a minute. */
+    lastUsedAt: string | null;
+    /** When it was revoked. A revoked token never verifies again. */
+    revokedAt: string | null;
+}
+export interface IssuedHeadStorefrontToken {
+    /** The whole token. Shown ONCE: put it in the storefront server's secrets now. */
+    token: string;
+    record: HeadStorefrontToken;
+}
+export declare const STOREFRONT_TOKEN_FIELDS = "\n  id\n  headId\n  name\n  prefix\n  createdAt\n  lastUsedAt\n  revokedAt\n";
+export declare const PRIVATE_TOKENS_QUERY = "\n  query HeadStorefrontTokens($headId: ID!) {\n    headStorefrontTokens(headId: $headId) { \n  id\n  headId\n  name\n  prefix\n  createdAt\n  lastUsedAt\n  revokedAt\n }\n  }\n";
+export declare const ISSUE_PRIVATE_TOKEN_MUTATION = "\n  mutation IssueHeadStorefrontToken($headId: ID!, $name: String!) {\n    issueHeadStorefrontToken(headId: $headId, name: $name) {\n      token\n      record { \n  id\n  headId\n  name\n  prefix\n  createdAt\n  lastUsedAt\n  revokedAt\n }\n    }\n  }\n";
+export declare const REVOKE_PRIVATE_TOKEN_MUTATION = "\n  mutation RevokeHeadStorefrontToken($id: ID!) {\n    revokeHeadStorefrontToken(id: $id) { \n  id\n  headId\n  name\n  prefix\n  createdAt\n  lastUsedAt\n  revokedAt\n }\n  }\n";
+/**
+ * Private storefront tokens per head (spec §6.3, §6.7, §15.21).
+ *
+ * A server-side storefront sends its token with
+ * `createStorefrontClient({ storeCode, privateToken, buyerIp })` from
+ * `@sixtyninecommerce/client`. It grants NO permission: it gives that server its
+ * own rate-limit budget and makes the platform key per-shopper budgets (and the
+ * form limiter) on the shopper address the server forwards. Never ship it to a
+ * browser — the storefront SDK refuses to (`CREDENTIAL_IN_BROWSER`).
+ *
+ * Read with `ReadSettings`, issued and revoked with `UpdateSettings`. At most 10
+ * live tokens per head (`HEAD_STOREFRONT_TOKEN_LIMIT`), which is room to rotate:
+ * issue the new one, deploy it, revoke the old. `issue` takes no idempotency key
+ * — its response is the credential, and no replay store may keep it.
+ */
+export interface HeadPrivateTokensModule {
+    /** A head's tokens, newest first, revoked ones included. `HEAD_NOT_FOUND` for another store's head. */
+    list(headId: string, options?: Call): Promise<HeadStorefrontToken[]>;
+    /**
+     * Issue a token for a head. The plaintext is in `token`, once; it cannot be
+     * read again. Refused `INVALID_STOREFRONT_TOKEN_NAME` (1-100 characters, no
+     * control characters) or `HEAD_STOREFRONT_TOKEN_LIMIT`.
+     */
+    issue(headId: string, input: {
+        name: string;
+    }, options?: Call): Promise<IssuedHeadStorefrontToken>;
+    /**
+     * Revoke a token. Terminal and idempotent. Every service stops honouring it
+     * within 15 seconds; the store's public channel token is untouched.
+     * `HEAD_STOREFRONT_TOKEN_NOT_FOUND` for another store's token.
+     */
+    revoke(id: string, options?: Call): Promise<HeadStorefrontToken>;
+}
 /**
  * The store's head registry (spec §6.7).
  *
@@ -99,5 +157,7 @@ export interface HeadsModule {
     delete(id: string, options?: Call): Promise<boolean>;
     /** Move the store's default head. There is no way to unset one, only to move it. */
     setDefault(id: string, options?: Call): Promise<Head>;
+    /** Each head's private storefront tokens (`s69p_`). */
+    privateTokens: HeadPrivateTokensModule;
 }
 export declare function createHeadsModule(transport: Transport): HeadsModule;

package/dist/heads/index.js

@@ -44,6 +44,33 @@ export const SET_DEFAULT_MUTATION = /* GraphQL */ `
     setDefaultChannelHead(id: $id) { ${HEAD_FIELDS} }
   }
 `;
+export const STOREFRONT_TOKEN_FIELDS = /* GraphQL */ `
+  id
+  headId
+  name
+  prefix
+  createdAt
+  lastUsedAt
+  revokedAt
+`;
+export const PRIVATE_TOKENS_QUERY = /* GraphQL */ `
+  query HeadStorefrontTokens($headId: ID!) {
+    headStorefrontTokens(headId: $headId) { ${STOREFRONT_TOKEN_FIELDS} }
+  }
+`;
+export const ISSUE_PRIVATE_TOKEN_MUTATION = /* GraphQL */ `
+  mutation IssueHeadStorefrontToken($headId: ID!, $name: String!) {
+    issueHeadStorefrontToken(headId: $headId, name: $name) {
+      token
+      record { ${STOREFRONT_TOKEN_FIELDS} }
+    }
+  }
+`;
+export const REVOKE_PRIVATE_TOKEN_MUTATION = /* GraphQL */ `
+  mutation RevokeHeadStorefrontToken($id: ID!) {
+    revokeHeadStorefrontToken(id: $id) { ${STOREFRONT_TOKEN_FIELDS} }
+  }
+`;
 export function createHeadsModule(transport) {
     return {
         async list(options) {
@@ -70,5 +97,23 @@ export function createHeadsModule(transport) {
             const data = await transport.graphql({ api: 'admin', query: SET_DEFAULT_MUTATION, variables: { id } }, options);
             return data.setDefaultChannelHead;
         },
+        privateTokens: {
+            async list(headId, options) {
+                const data = await transport.graphql({ api: 'admin', query: PRIVATE_TOKENS_QUERY, variables: { headId } }, options);
+                return data.headStorefrontTokens;
+            },
+            async issue(headId, input, options) {
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: ISSUE_PRIVATE_TOKEN_MUTATION,
+                    variables: { headId, name: input.name },
+                }, options);
+                return data.issueHeadStorefrontToken;
+            },
+            async revoke(id, options) {
+                const data = await transport.graphql({ api: 'admin', query: REVOKE_PRIVATE_TOKEN_MUTATION, variables: { id } }, options);
+                return data.revokeHeadStorefrontToken;
+            },
+        },
     };
 }