@sixtyninecommerce/admin 0.6.0 → 0.8.0

package/dist/apps/credential.js

@@ -1,5 +1,5 @@
-import { errorFromResponse, TransportError } from '@sixtyninecommerce/core';
-import { importAppPrivateKey, signAppAssertion, } from './assertion.js';
+import { errorFromResponse, RateLimitedError, TransportError } from '@sixtyninecommerce/core';
+import { assertionAudience, importAppPrivateKey, signAppAssertion, } from './assertion.js';
 /** Refresh this long before expiry, so no call goes out on a dying token. */
 const REFRESH_MARGIN_MS = 60_000;
 /**
@@ -8,6 +8,16 @@ const REFRESH_MARGIN_MS = 60_000;
  * budgeted 15 s could block for 45 while a stalled mint ran to its own deadline.
  */
 const EXCHANGE_TIMEOUT_MS = 15_000;
+/**
+ * Longest hold-off this credential takes from a 429's `Retry-After`.
+ *
+ * The exchange's budget is measured over a trailing minute, so a longer wait is
+ * a mistyped limiter or an intermediary's own throttle — and obeying it
+ * literally would keep an app from minting for as long as the hint says, on a
+ * route whose bucket has certainly freed up by then. The caller still sees the
+ * server's uncapped number on `error.retryAfterSeconds`.
+ */
+const MAX_RATE_LIMIT_HOLD_MS = 60_000;
 export function createAppCredential(app, installationId, vendureUrl, fetchImpl) {
     let token = '';
     let expiresAt = 0;
@@ -17,7 +27,33 @@ export function createAppCredential(app, installationId, vendureUrl, fetchImpl)
     /** The dead bearer the in-flight mint is REPLACING, for `refresh()`. */
     let refreshingFrom = null;
     let key = null;
+    /** Instant the exchange's own 429 said its budget frees up; 0 ⇒ not limited. */
+    let rateLimitedUntil = 0;
+    /** The refusal a caller gets while the exchange's stated window has not passed. */
+    function rateLimited(seconds) {
+        return new RateLimitedError({
+            code: 'RATE_LIMITED',
+            message: `The app token exchange refused the last attempt for this installation and asked to be ` +
+                `called again in ${String(seconds)}s. No request was sent.`,
+            status: 429,
+            service: 'vendure',
+            retryAfterSeconds: seconds,
+        });
+    }
     async function mint() {
+        // HONOUR THE 429 THE EXCHANGE ALREADY ANSWERED, without spending a round
+        // trip to be told the same thing. `Retry-After` is the server naming the
+        // instant its bucket frees up, and a client that keeps calling through it
+        // is the traffic the budget exists to stop. The refusal carries the
+        // REMAINING wait, so the caller's own backoff — and the transport's retry
+        // loop, which reads `retryAfterSeconds` — paces on the time actually left.
+        //
+        // Only MINTING is held off. `current()` answers from the cached bearer
+        // above, so an app with a live token is untouched by a window it will never
+        // reach.
+        const holdMs = rateLimitedUntil - Date.now();
+        if (holdMs > 0)
+            throw rateLimited(Math.ceil(holdMs / 1000));
         // The generation this mint belongs to. An `invalidate()` that lands while
         // this is in flight bumps it, and the result is then returned to the caller
         // but NOT cached — otherwise the token the server has just killed would be
@@ -30,6 +66,10 @@ export function createAppCredential(app, installationId, vendureUrl, fetchImpl)
             appId: app.appId,
             installationId,
             kid: app.kid,
+            // The SAME `vendureUrl` the exchange URL is built from, reduced to its
+            // origin — so the claim and the endpoint can never name two different
+            // deployments, whatever shape the caller configured.
+            audience: assertionAudience(vendureUrl),
         });
         // Trailing slash stripped, as every other URL in the client is: a
         // `vendureUrl` of `https://api.example.test/` works for every GraphQL call
@@ -65,8 +105,19 @@ export function createAppCredential(app, installationId, vendureUrl, fetchImpl)
         }
         if (!response.ok) {
             // problem+json first, legacy second — the exchange answers the same shape
-            // every other refusal on this platform does.
-            throw await errorFromResponse(response, 'vendure');
+            // every other refusal on this platform does. `errorFromResponse` folds the
+            // `Retry-After` header into `retryAfterSeconds` for a 429 whose body left
+            // it out, so this reads one field either way.
+            const error = await errorFromResponse(response, 'vendure');
+            if (error.status === 429) {
+                const seconds = typeof error.retryAfterSeconds === 'number' && Number.isFinite(error.retryAfterSeconds)
+                    ? Math.max(0, error.retryAfterSeconds)
+                    : 0;
+                // A 429 with no usable hint sets no hold: guessing a window would be
+                // this client inventing a throttle the server never asked for.
+                rateLimitedUntil = Date.now() + Math.min(seconds * 1_000, MAX_RATE_LIMIT_HOLD_MS);
+            }
+            throw error;
         }
         // Read inside the same guard as the request: an abort that fires while the
         // body is still streaming would otherwise escape as a raw `AbortError`,

package/dist/apps/index.d.ts

@@ -54,6 +54,17 @@ export interface AppInstallation {
 }
 /** What an approver agrees to. Every field omitted means "keep what was granted". */
 export interface ApproveConsentInput {
+    /**
+     * The `pendingConsentReasons` that were on screen when the approver read
+     * them.
+     *
+     * Optional, and worth sending from any surface a human reads: the engine
+     * refuses the approval when the app has changed since, so a re-registration
+     * between the screen and the button cannot have an escalation ratified by
+     * somebody who was never shown it. Omit it and the approval applies to
+     * whatever is pending at the moment it lands.
+     */
+    acknowledgedConsentReasons?: string[];
     grantedPermissions?: string[];
     grantedFieldOwnership?: string[];
     /**

package/dist/client.d.ts

@@ -1,19 +1,29 @@
 import { type DeprecationNotice, type RateLimitInfo, type RetryPolicy, type TenantContext, type TenantScope } from '@sixtyninecommerce/core';
 import { type ApiTokensModule } from './api-tokens/index.js';
+import { type AppInstallationConfigModule } from './apps/config.js';
 import { type AppCredentialConfig } from './apps/credential.js';
 import { type AppsModule } from './apps/index.js';
 import { type AuditModule } from './audit/index.js';
 import { type AuthModule } from './auth/index.js';
 import { type FormsModule } from './content/forms.js';
+import { type CustomObjectsModule } from './custom-objects/index.js';
+import { type CustomersModule } from './customers/index.js';
+import { type DocumentsModule } from './documents/index.js';
 import { type HeadsModule } from './heads/index.js';
+import { type JobsModule } from './jobs/index.js';
 import { type LocationsModule } from './locations/index.js';
 import { type MetaModule } from './meta/index.js';
+import { type MetafieldsModule } from './metafields/index.js';
+import { type OrdersModule } from './orders/index.js';
+import { type PaymentsModule } from './payments/index.js';
 import { type PlatformAppsModule } from './platform/apps.js';
 import { type PlatformModule } from './platform/provision-store.js';
 import { type RedirectsModule } from './seo/redirects.js';
+import { type TaxModule } from './tax/index.js';
 import { type CapabilitiesModule } from './tenant/capabilities.js';
 import { type ChannelsModule } from './tenant/channels.js';
 import { type RetentionModule } from './tenant/retention.js';
+import { type UploadsModule } from './uploads/index.js';
 export interface AdminClientConfig {
     urls: {
         vendureUrl: string;
@@ -60,21 +70,64 @@ export interface AdminClient {
     auth: AuthModule;
     apiTokens: ApiTokensModule;
     /** Installing and managing apps on the ACTIVE store. Needs `InstallApps`. */
-    apps: AppsModule;
+    apps: AppsModule & {
+        /** One installation's own surfaces. `config` is its settings form (spec §8.13). */
+        installation: {
+            config: AppInstallationConfigModule;
+        };
+    };
     audit: AuditModule;
     channels: ChannelsModule;
     content: {
         forms: FormsModule;
     };
+    /**
+     * Invoices, credit notes and packing slips: issuing them, the numbered facts
+     * they were built from, and the store's own extension blocks (spec §8.5).
+     */
+    documents: DocumentsModule;
+    /**
+     * Customers — the commerce master record, plus their groups and addresses.
+     * `list`/`get` need `ReadCustomer`, the writes `UpdateCustomer`, and `erase`
+     * `DeleteCustomer`. `create` is CHANNEL-SCOPED: core `createCustomer` shares
+     * a customer across channels by email and is not reachable through this SDK.
+     */
+    customers: CustomersModule;
     /** The store's head registry: every client surface it serves (spec §6.7). */
     heads: HeadsModule;
+    /** Every long-running operation the platform runs, under one resource (spec §6.11). */
+    jobs: JobsModule;
     /** Stock-location profiles (spec §8.7); `TenantContext.location` names one by id. */
     locations: LocationsModule;
     /** Labels, transitions, permission and plugin catalogs, settings schemas. */
     meta: MetaModule;
+    /**
+     * An app's own private state, keyed `(container, key)` (spec §8.13). Only an
+     * installation token reaches it.
+     */
+    customObjects: CustomObjectsModule;
+    /** App and platform custom data on core entities (spec §8.13, §8.4). */
+    metafields: MetafieldsModule;
+    /**
+     * Surcharges on a placed order (spec §8.6 for `taxClass`), and the deposit
+     * flow: park, read the payment position, settle (spec §8.2, §15.5).
+     */
+    orders: OrdersModule;
+    /**
+     * Payment-provider accounts, terminals and readiness (spec §8.9), and money
+     * recorded against an order with what it stands at (spec §8.2).
+     */
+    payments: PaymentsModule;
     seo: {
         redirects: RedirectsModule;
     };
+    /** The store's own tax classes and their per-country mappings (spec §8.6). */
+    tax: TaxModule;
+    /**
+     * Signed direct-to-storage uploads (spec §6.11): reserve a place, PUT the
+     * bytes straight to the object store, then hand the id to a consuming call.
+     */
+    uploads: UploadsModule;
     /** The calling tenant's own settings. Always the ACTIVE channel — no channel argument. */
     tenant: {
         capabilities: CapabilitiesModule;

package/dist/client.js

@@ -1,19 +1,29 @@
 import { createChannelResolver, createTransport, mergeTenant, UNSCOPED_TENANT, ValidationError, } from '@sixtyninecommerce/core';
 import { createApiTokensModule } from './api-tokens/index.js';
+import { createAppConfigModule } from './apps/config.js';
 import { createAppCredential, } from './apps/credential.js';
 import { createAppsModule } from './apps/index.js';
 import { createAuditModule } from './audit/index.js';
 import { createAuthModule } from './auth/index.js';
 import { createFormsModule } from './content/forms.js';
+import { createCustomObjectsModule } from './custom-objects/index.js';
+import { createCustomersModule } from './customers/index.js';
+import { createDocumentsModule } from './documents/index.js';
 import { createHeadsModule } from './heads/index.js';
+import { createJobsModule } from './jobs/index.js';
 import { createLocationsModule } from './locations/index.js';
 import { createMetaModule } from './meta/index.js';
+import { createMetafieldsModule } from './metafields/index.js';
+import { createOrdersModule } from './orders/index.js';
+import { createPaymentsModule } from './payments/index.js';
 import { createPlatformAppsModule } from './platform/apps.js';
 import { createPlatformModule } from './platform/provision-store.js';
 import { createRedirectsModule } from './seo/redirects.js';
+import { createTaxModule } from './tax/index.js';
 import { createCapabilitiesModule } from './tenant/capabilities.js';
 import { createChannelsModule } from './tenant/channels.js';
 import { createRetentionModule } from './tenant/retention.js';
+import { createUploadsModule } from './uploads/index.js';
 /**
  * An admin credential in a browser is a credential the whole internet can read
  * (spec §18 amendment 3, §15.21). A SESSION bearer is fine there — that is what
@@ -139,6 +149,17 @@ function assertSessionIsWritable(session) {
         service: 'vendure',
     });
 }
+/**
+ * `apps.installation` is BOTH a call and a namespace: `installation(id)` reads
+ * one, and `installation.config` is that installation's settings form. The two
+ * belong to the same noun, so they share the path rather than growing a second
+ * one (`apps.config`) that a reader would have to learn separately.
+ */
+function buildAppsModule(transport) {
+    const apps = createAppsModule(transport);
+    const installation = Object.assign((id, options) => apps.installation(id, options), { config: createAppConfigModule(transport) });
+    return { ...apps, installation };
+}
 export function createAdminClient(config) {
     assertNotInBrowser(config.auth);
     const resolver = createChannelResolver({
@@ -324,14 +345,26 @@ function buildClient(config, overrides, resolver, shared, credential) {
             },
         }),
         apiTokens: createApiTokensModule(transport),
-        apps: createAppsModule(transport),
+        apps: buildAppsModule(transport),
         audit: createAuditModule(transport),
         channels: createChannelsModule(resolver),
         content: { forms: createFormsModule(transport) },
         heads: createHeadsModule(transport),
+        jobs: createJobsModule(transport),
         locations: createLocationsModule(transport),
         meta: createMetaModule(transport),
+        customObjects: createCustomObjectsModule(transport),
+        metafields: createMetafieldsModule(transport),
+        orders: createOrdersModule(transport),
+        payments: createPaymentsModule(transport),
+        documents: createDocumentsModule(transport),
+        customers: createCustomersModule(transport),
         seo: { redirects: createRedirectsModule(transport) },
+        tax: createTaxModule(transport),
+        // The PUT goes to the object store, not to this platform, so it needs the
+        // caller's own fetch rather than the transport — which would attach the
+        // tenant headers and the bearer to a request that must carry neither.
+        uploads: createUploadsModule(transport, config.fetch ?? globalThis.fetch),
         tenant: {
             capabilities: createCapabilitiesModule(transport),
             retention: createRetentionModule(transport),

package/dist/custom-objects/index.d.ts

@@ -0,0 +1,66 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * A document an app keeps for itself (spec §8.13).
+ *
+ * The platform stores and returns the value and interprets none of it. The one
+ * exception is the reserved `$config` container, which holds the merchant's
+ * settings and is reached through `apps.installation.config` instead — these
+ * methods refuse it.
+ */
+export interface CustomObject {
+    container: string;
+    key: string;
+    /** Whatever JSON was written. */
+    value: unknown;
+    /** The stored value's size in bytes, which is what the quota counts. */
+    sizeBytes: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * An app's own state, addressed by `(container, key)`.
+ *
+ * **Only an installation token reaches these.** They are the app's private
+ * bookkeeping: a human session — even a SuperAdmin's — is refused with
+ * `CUSTOM_OBJECT_FORBIDDEN`, and one installation never sees another's rows,
+ * on the same channel or on any other. That is what makes it safe for an app to
+ * keep an API cursor or a field map here.
+ *
+ * **Two quotas, per installation per store.** A single document may be 128 KiB,
+ * and an installation may hold 10,000 live objects
+ * (`CUSTOM_OBJECT_TOO_LARGE`, `CUSTOM_OBJECT_LIMIT_REACHED`). The row quota is
+ * checked only when a NEW key is written, so a full installation can still
+ * shrink a value it already has.
+ *
+ * **Names are capped.** A container is 1-64 characters, starts with a lowercase
+ * letter or digit and uses only lowercase letters, digits, `-` and `_`; a key is
+ * 1-200 characters and carries no control characters. `$config` is reserved for
+ * the settings form and is reached through `apps.installation.config`.
+ *
+ * **The value must be JSON that survives a round trip.** `undefined`, a
+ * function and a non-finite number are refused at any depth
+ * (`CUSTOM_OBJECT_INVALID`) rather than stored as `null` and read back as
+ * something nobody wrote.
+ */
+export interface CustomObjectsModule {
+    /** One container's objects, newest first. */
+    list(container: string, options?: ListOptions): Promise<Page<CustomObject>>;
+    /** One object. Unknown `(container, key)` is `CUSTOM_OBJECT_NOT_FOUND`. */
+    get(container: string, key: string, options?: Call): Promise<CustomObject>;
+    /**
+     * Create or replace one object. Last write wins.
+     *
+     * An `idempotencyKey` is forwarded if you pass one, but the route does NOT
+     * honour it: the store namespaces keys by channel while these rows are per
+     * installation, so a shared namespace would let one app's key collide with
+     * another's. A PUT that replaces a value by key needs no key of its own —
+     * repeating it is the same as doing it once.
+     */
+    set(container: string, key: string, value: unknown, options?: Call & {
+        idempotencyKey?: string;
+    }): Promise<CustomObject>;
+    /** Delete one object. Deleting what is not there is `CUSTOM_OBJECT_NOT_FOUND`. */
+    delete(container: string, key: string, options?: Call): Promise<void>;
+}
+export declare function createCustomObjectsModule(transport: Transport): CustomObjectsModule;

package/dist/custom-objects/index.js

@@ -0,0 +1,48 @@
+import { createPage, PLATFORM_PASSTHROUGH_KEYS, readRestPage, } from '@sixtyninecommerce/core';
+/**
+ * `value` holds the APP's own JSON, so its inner keys must survive the
+ * transport's case conversion untouched.
+ *
+ * Without this an app that writes `{ order_ref: 1 }` reads back
+ * `{ orderRef: 1 }` — and the round trip hides it, because the read path
+ * converts the mangled key into something that looks right while the stored row
+ * is wrong. This is the same trap `PLATFORM_PASSTHROUGH_KEYS` exists for; the
+ * key is added here rather than to that shared set because `value` is a common
+ * enough name that preserving it platform-wide would change modules that mean
+ * something else by it.
+ */
+const PRESERVE = new Set([...PLATFORM_PASSTHROUGH_KEYS, 'value']);
+const segment = (value) => encodeURIComponent(value);
+export function createCustomObjectsModule(transport) {
+    async function list(container, options) {
+        const body = await transport.rest('plugins', {
+            method: 'GET',
+            path: `/custom-objects/${segment(container)}`,
+            query: { after: options?.after, limit: options?.limit },
+        }, { ...options, preserveKeys: PRESERVE });
+        const { items, meta } = readRestPage(body);
+        return createPage(items, meta, (cursor) => list(container, { ...options, after: cursor }));
+    }
+    return {
+        list,
+        async get(container, key, options) {
+            return await transport.rest('plugins', { method: 'GET', path: `/custom-objects/${segment(container)}/${segment(key)}` }, { ...options, preserveKeys: PRESERVE });
+        },
+        async set(container, key, value, options) {
+            return await transport.rest('plugins', {
+                method: 'PUT',
+                path: `/custom-objects/${segment(container)}/${segment(key)}`,
+                // Wrapped rather than sent bare so the body can gain a field later;
+                // a bare JSON value has nowhere to put one.
+                body: { value },
+            }, { ...options, preserveKeys: PRESERVE });
+        },
+        async delete(container, key, options) {
+            await transport.rest('plugins', {
+                method: 'DELETE',
+                path: `/custom-objects/${segment(container)}/${segment(key)}`,
+                expect: 'void',
+            }, options);
+        },
+    };
+}

package/dist/customers/index.d.ts

@@ -0,0 +1,225 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * Customers — the commerce master record (headless spec §6.5).
+ *
+ * Commerce owns customer identity and addresses; a vertical stores a
+ * `platformCustomerId` and asks here. The two things worth knowing before
+ * reading further are both traps this module exists to close:
+ *
+ * 1. **`create` wraps `createChannelCustomer`, never core `createCustomer`.**
+ *    Vendure's own mutation silently SHARES a customer across channels when the
+ *    email already exists anywhere on the platform (ADR-016): it finds that
+ *    customer and pushes the new channel onto them. On a multi-tenant platform
+ *    that is a cross-tenant data leak wearing the clothes of a convenience.
+ *    There is no way to reach the leaking path through this SDK.
+ * 2. **`erase` is a scrub, not a delete.** It removes the person and keeps the
+ *    record, the orders and the documents. It is the only destructive customer
+ *    operation the platform has.
+ */
+export declare const CUSTOMER_FIELDS = "\n  id\n  createdAt\n  updatedAt\n  title\n  firstName\n  lastName\n  emailAddress\n  phoneNumber\n  groups {\n    id\n    name\n  }\n";
+export declare const CUSTOMER_ADDRESS_FIELDS = "\n  id\n  fullName\n  company\n  streetLine1\n  streetLine2\n  city\n  province\n  postalCode\n  country {\n    code\n    name\n  }\n  phoneNumber\n  defaultShippingAddress\n  defaultBillingAddress\n";
+export declare const LIST_QUERY = "\n  query Customers($options: CustomerListOptions) {\n    customers(options: $options) {\n      items { \n  id\n  createdAt\n  updatedAt\n  title\n  firstName\n  lastName\n  emailAddress\n  phoneNumber\n  groups {\n    id\n    name\n  }\n }\n      totalItems\n    }\n  }\n";
+export declare const GET_QUERY = "\n  query CustomerById($id: ID!) {\n    customer(id: $id) { \n  id\n  createdAt\n  updatedAt\n  title\n  firstName\n  lastName\n  emailAddress\n  phoneNumber\n  groups {\n    id\n    name\n  }\n }\n  }\n";
+export declare const ADDRESSES_QUERY = "\n  query CustomerAddresses($id: ID!) {\n    customer(id: $id) {\n      id\n      addresses { \n  id\n  fullName\n  company\n  streetLine1\n  streetLine2\n  city\n  province\n  postalCode\n  country {\n    code\n    name\n  }\n  phoneNumber\n  defaultShippingAddress\n  defaultBillingAddress\n }\n    }\n  }\n";
+/**
+ * The CHANNEL-SCOPED creation mutation. See the module docblock — core
+ * `createCustomer` is not an option, and this SDK exposes no path to it.
+ */
+export declare const CREATE_MUTATION = "\n  mutation CreateChannelCustomer($input: CreateCustomerInput!, $password: String) {\n    createChannelCustomer(input: $input, password: $password) {\n      id\n      emailAddress\n      createdNew\n    }\n  }\n";
+export declare const UPDATE_MUTATION = "\n  mutation UpdateCustomer($input: UpdateCustomerInput!) {\n    updateCustomer(input: $input) {\n      ... on Customer { \n  id\n  createdAt\n  updatedAt\n  title\n  firstName\n  lastName\n  emailAddress\n  phoneNumber\n  groups {\n    id\n    name\n  }\n }\n      ... on ErrorResult { errorCode message }\n    }\n  }\n";
+export declare const INVITE_MUTATION = "\n  mutation InviteCustomer($customerId: ID!, $mode: CustomerInviteMode) {\n    inviteCustomer(customerId: $customerId, mode: $mode) {\n      customerId\n      emailAddress\n      mode\n      sentAt\n    }\n  }\n";
+export declare const RESEND_INVITE_MUTATION = "\n  mutation ResendCustomerInvitation($customerId: ID!, $mode: CustomerInviteMode) {\n    resendCustomerInvitation(customerId: $customerId, mode: $mode) {\n      customerId\n      emailAddress\n      mode\n      sentAt\n    }\n  }\n";
+export declare const ERASE_MUTATION = "\n  mutation EraseCustomer(\n    $customerId: ID!\n    $reason: String!\n    $force: Boolean\n    $idempotencyKey: String\n  ) {\n    eraseCustomer(\n      customerId: $customerId\n      reason: $reason\n      force: $force\n      idempotencyKey: $idempotencyKey\n    ) {\n      customerId\n      erasedAt\n      ordersRetained\n      documentsRetained\n      forced\n      reason\n    }\n  }\n";
+export declare const ERASURE_QUERY = "\n  query CustomerErasure($customerId: ID!) {\n    customerErasure(customerId: $customerId) {\n      customerId\n      erasedAt\n      ordersRetained\n      documentsRetained\n      forced\n      reason\n    }\n  }\n";
+export declare const ADD_TO_GROUP_MUTATION = "\n  mutation AddCustomersToGroup($customerGroupId: ID!, $customerIds: [ID!]!) {\n    addCustomersToGroup(customerGroupId: $customerGroupId, customerIds: $customerIds) {\n      id\n      name\n    }\n  }\n";
+export declare const REMOVE_FROM_GROUP_MUTATION = "\n  mutation RemoveCustomersFromGroup($customerGroupId: ID!, $customerIds: [ID!]!) {\n    removeCustomersFromGroup(customerGroupId: $customerGroupId, customerIds: $customerIds) {\n      id\n      name\n    }\n  }\n";
+export declare const CREATE_ADDRESS_MUTATION = "\n  mutation CreateCustomerAddress($customerId: ID!, $input: CreateAddressInput!) {\n    createCustomerAddress(customerId: $customerId, input: $input) {\n      \n  id\n  fullName\n  company\n  streetLine1\n  streetLine2\n  city\n  province\n  postalCode\n  country {\n    code\n    name\n  }\n  phoneNumber\n  defaultShippingAddress\n  defaultBillingAddress\n\n    }\n  }\n";
+export declare const UPDATE_ADDRESS_MUTATION = "\n  mutation UpdateCustomerAddress($input: UpdateAddressInput!) {\n    updateCustomerAddress(input: $input) { \n  id\n  fullName\n  company\n  streetLine1\n  streetLine2\n  city\n  province\n  postalCode\n  country {\n    code\n    name\n  }\n  phoneNumber\n  defaultShippingAddress\n  defaultBillingAddress\n }\n  }\n";
+export declare const DELETE_ADDRESS_MUTATION = "\n  mutation DeleteCustomerAddress($id: ID!) {\n    deleteCustomerAddress(id: $id) { success }\n  }\n";
+export interface CustomerGroupRef {
+    id: string;
+    name: string;
+}
+export interface Customer {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    title: string | null;
+    firstName: string;
+    lastName: string;
+    emailAddress: string;
+    phoneNumber: string | null;
+    groups: CustomerGroupRef[];
+    /** Forward-compat: fields a later release adds arrive camelised and untouched. */
+    [extra: string]: unknown;
+}
+export interface CustomerAddress {
+    id: string;
+    fullName: string | null;
+    company: string | null;
+    streetLine1: string;
+    streetLine2: string | null;
+    city: string | null;
+    province: string | null;
+    postalCode: string | null;
+    country: {
+        code: string;
+        name: string;
+    } | null;
+    phoneNumber: string | null;
+    defaultShippingAddress: boolean | null;
+    defaultBillingAddress: boolean | null;
+    [extra: string]: unknown;
+}
+export interface CreateCustomerInput {
+    emailAddress: string;
+    firstName: string;
+    lastName: string;
+    title?: string;
+    phoneNumber?: string;
+    customFields?: Record<string, unknown>;
+}
+export interface UpdateCustomerInput {
+    title?: string;
+    firstName?: string;
+    lastName?: string;
+    phoneNumber?: string;
+    emailAddress?: string;
+    customFields?: Record<string, unknown>;
+}
+/** What `createChannelCustomer` answers. */
+export interface CreatedCustomer {
+    id: string;
+    emailAddress: string;
+    /**
+     * `false` when a customer with this email already existed ON THIS CHANNEL and
+     * was returned instead. It is never another channel's customer — that is the
+     * whole point of the channel-scoped mutation.
+     */
+    createdNew: boolean;
+}
+export type CustomerInviteMode = 'PASSWORD_SETUP' | 'MAGIC_LINK';
+export interface CustomerInvitation {
+    customerId: string;
+    emailAddress: string;
+    mode: CustomerInviteMode;
+    sentAt: string;
+}
+/** The record of an erasure. See {@link CustomersModule.erase}. */
+export interface CustomerErasureRecord {
+    customerId: string;
+    erasedAt: string;
+    /** Placed orders left standing — an order is a document fact. */
+    ordersRetained: number;
+    /**
+     * ORDER DOCUMENTS left standing: invoices and credit notes issued against
+     * this customer's orders on this channel.
+     *
+     * Accounts-receivable documents (`ar_invoice`, `ar_credit_note`) are NOT
+     * counted — a consolidated AR invoice spans several orders and is not
+     * reachable through the order join — so a B2B tenant's full document set is
+     * larger than this number.
+     */
+    documentsRetained: number;
+    /** A SuperAdmin overrode the open-unpaid-order refusal. */
+    forced: boolean;
+    reason: string;
+}
+export interface EraseCustomerOptions extends Call {
+    /** Recorded on the erasure record. Required — it is the evidence it was honoured. */
+    reason: string;
+    /**
+     * Erase despite an open unpaid order. SuperAdmin only, refused with
+     * `CUSTOMER_ERASURE_FORCE_FORBIDDEN` otherwise, and recorded on the record.
+     */
+    force?: boolean;
+    /** Your own request id, recorded for provenance. */
+    idempotencyKey?: string;
+}
+export interface CustomerAddressesModule {
+    list(customerId: string, options?: Call): Promise<CustomerAddress[]>;
+    create(customerId: string, input: Record<string, unknown>, options?: Call): Promise<CustomerAddress>;
+    update(input: {
+        id: string;
+    } & Record<string, unknown>, options?: Call): Promise<CustomerAddress>;
+    delete(id: string, options?: Call): Promise<void>;
+}
+export interface CustomerGroupsModule {
+    /** Add customers to a group. Emits one `customer.group_changed` per customer. */
+    add(groupId: string, customerIds: string[], options?: Call): Promise<CustomerGroupRef>;
+    remove(groupId: string, customerIds: string[], options?: Call): Promise<CustomerGroupRef>;
+}
+export interface CustomersModule {
+    list(options?: ListOptions): Promise<Page<Customer>>;
+    get(id: string, options?: Call): Promise<Customer | null>;
+    /**
+     * Create a customer ON THIS CHANNEL. Never creates credentials — `invite`
+     * does that.
+     */
+    create(input: CreateCustomerInput, options?: Call & {
+        password?: string;
+    }): Promise<CreatedCustomer>;
+    update(id: string, input: UpdateCustomerInput, options?: Call): Promise<Customer>;
+    /**
+     * Mail the customer a way in: a set-password link, or a magic-link sign-in.
+     *
+     * Not the storefront's forgot-password screen, which mails a password RESET
+     * — something a customer who has never had an account did not ask for.
+     */
+    invite(id: string, options?: Call & {
+        mode?: CustomerInviteMode;
+        resend?: boolean;
+    }): Promise<CustomerInvitation>;
+    /**
+     * GDPR erasure: scrub the person, keep the record.
+     *
+     * The customer row, their orders and their invoices remain — an invoice that
+     * cannot be reproduced is a different problem from a privacy one. Emits
+     * `customer.deleted`.
+     *
+     * What "the person" covers is enumerated BY COLUMN on the platform rather
+     * than remembered: every column of the commerce database classified as
+     * personal data is scrubbed or tombstoned, retained columns and their reasons
+     * are listed with it, and the plugins-side event log is redacted too. The
+     * classification is regenerated from the live schema and a build
+     * fails on any column it does not answer for — including columns on tables
+     * that name no customer at all, which is how an invoice email log kept an
+     * erased person's address.
+     *
+     * Refused while a retention hold is active (`RETENTION_HOLD_ACTIVE`), while
+     * the customer is party to an open unpaid order (`CUSTOMER_HAS_OPEN_ORDERS`;
+     * a SuperAdmin may pass `force`), while they hold a subscription that has not
+     * ended (`CUSTOMER_HAS_ACTIVE_SUBSCRIPTIONS`), when their login is shared with
+     * another store on the platform (`CUSTOMER_SHARED_ACROSS_STORES`), and when
+     * the tenant context names the platform root channel rather than the
+     * customer's own (`CUSTOMER_ERASURE_CHANNEL_INVALID`).
+     *
+     * `force` overrides the OPEN-ORDER refusal and nothing else. A live payment
+     * mandate will charge this person again next cycle, and a shared login belongs
+     * to a merchant who asked for nothing — neither is a SuperAdmin's to waive.
+     *
+     * Idempotent: erasing an already-erased customer returns the original record.
+     *
+     * Platform events emitted BEFORE the erasure lose the name and email too. That
+     * log lives in another service's database, which the erasure cannot reach, so
+     * the redaction is triggered there by the arrival of this erasure's own
+     * `customer.deleted` event: ingesting it queues the redaction in the same
+     * transaction, and a worker applies it afterwards, so this call RETURNS
+     * BEFORE the log has been rewritten. Two one-minute ticks sit in between (the
+     * relay, then the drain), so it is up to about two minutes. A periodic
+     * reconcile covers deletions ingested before that release shipped, and a
+     * redaction that keeps failing is parked and reported in the plugins log —
+     * nothing on the returned record reflects either.
+     *
+     * That event keeps its ids and its `external_refs`: it is the one moment an
+     * ESP, ERP, CRM or PSP can erase its own copy of the person, and blanking it
+     * would destroy the only keys to them.
+     */
+    erase(id: string, options: EraseCustomerOptions): Promise<CustomerErasureRecord>;
+    /** The erasure record, or `null` if this customer has not been erased. */
+    erasure(id: string, options?: Call): Promise<CustomerErasureRecord | null>;
+    groups: CustomerGroupsModule;
+    addresses: CustomerAddressesModule;
+}
+export declare function createCustomersModule(transport: Transport): CustomersModule;