@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/platform/legal-entities.d.ts

@@ -0,0 +1,139 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { AdminClientConfig } from '../client.js';
+import type { Call, ListOptions } from '../types.js';
+import { type PlatformLegalEntityNumberingModule } from './legal-entity-numbering.js';
+/**
+ * A company that issues a store's invoices (multi-region spec §7.1): its legal name, tax numbers,
+ * registered office and fiscal time zone. One or more stores trade under it. Its `id` is the
+ * engine's Seller id.
+ */
+export interface LegalEntity {
+    id: string;
+    /** The Seller's name, set when it was created. Read-only: email store names fall back to it. */
+    name: string;
+    legalName: string | null;
+    vatNumber: string | null;
+    vatNumberUk: string | null;
+    eoriNumber: string | null;
+    registrationNumber: string | null;
+    registeredAddressLine1: string | null;
+    registeredAddressLine2: string | null;
+    registeredCity: string | null;
+    registeredPostalCode: string | null;
+    registeredProvince: string | null;
+    /** Upper-case ISO 3166-1 alpha-2. */
+    registeredCountry: string | null;
+    /** IANA time zone the fiscal year runs in (numbering resets), such as `Europe/Amsterdam`. */
+    timezone: string | null;
+    /** The entity's stores the caller may read; `storeCount` counts them all. */
+    stores: LegalEntityStore[];
+    storeCount: number;
+    /**
+     * Whether the caller may change it: a SuperAdmin, or a caller holding `UpdateSeller` on every one
+     * of its stores. Show the entity read-only when false.
+     */
+    editable: boolean;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LegalEntityStore {
+    id: string;
+    code: string;
+}
+/**
+ * The legal fields of an entity. Values are trimmed by the engine. A field sent as `null` or `''`
+ * is cleared, the legal name aside; a field left out is kept.
+ */
+export interface LegalEntityFields {
+    vatNumber?: string | null;
+    vatNumberUk?: string | null;
+    eoriNumber?: string | null;
+    registrationNumber?: string | null;
+    registeredAddressLine1?: string | null;
+    registeredAddressLine2?: string | null;
+    registeredCity?: string | null;
+    registeredPostalCode?: string | null;
+    registeredProvince?: string | null;
+    /** Upper-case ISO 3166-1 alpha-2, such as `NL`; anything else is `INVALID_COUNTRY_CODE`. */
+    registeredCountry?: string | null;
+    /** An IANA time zone; a fixed offset or an unknown name is `INVALID_TIMEZONE`. */
+    timezone?: string | null;
+}
+export interface CreateLegalEntityInput extends LegalEntityFields {
+    /** Required, and never empty: every invoice prints it. */
+    legalName: string;
+    /** Defaults to the legal name. */
+    name?: string;
+}
+export interface UpdateLegalEntityInput extends LegalEntityFields {
+    /** Changed when given; it can never be cleared (`LEGAL_ENTITY_FIELD_INVALID`). */
+    legalName?: string;
+}
+export interface LegalEntityListOptions extends ListOptions {
+    /** Matches the legal name, name, VAT or registration number, case-insensitively, as typed. */
+    term?: string;
+}
+/**
+ * `admin.platform.legalEntities` — the platform's legal entities (multi-region spec §7.1, decision
+ * 35 / Q9). Every method needs a human session: an API token or an app credential is refused with
+ * `PLATFORM_REQUIRES_SESSION` before anything is sent. A SuperAdmin needs no tenant on the client.
+ *
+ * - `list` and `create` are SuperAdmin-only (`FORBIDDEN` otherwise).
+ * - `get` answers the SuperAdmin any entity; anyone else only an entity whose every store they hold
+ *   `ReadSettings` on, and `SHARED_SELLER_NOT_ALLOWED` (403) for one they hold it on only some
+ *   stores of. Read the active store's entity with `admin.tenant.legalEntity` instead.
+ * - `update` needs `UpdateSeller` on every store of the entity (`SHARED_SELLER_NOT_ALLOWED`), and
+ *   copies its legal name, VAT, EORI and registration numbers onto every one of them in the same
+ *   transaction. The registered office and time zone are the entity's alone.
+ *
+ * An entity created with no store is not listed until a store is created under it, and only a
+ * SuperAdmin reads it by id. A store created under it, or moved onto it, takes its legal name and
+ * numbers.
+ *
+ * Neither write is deduplicated by an idempotency key (they are Admin API mutations). `update` is
+ * safe to repeat. `create` is not, and a lost answer cannot be recovered through this module: the
+ * new entity has no store yet, so `list` does not return it and its id went with the answer.
+ * Repeating the create makes a second entity, so confirm with the platform operator before you
+ * retry one whose outcome is unknown.
+ */
+export interface PlatformLegalEntitiesModule {
+    /**
+     * Every legal entity with at least one store, by legal name. Pages default to 50; a `limit` above
+     * 100 is refused with `INVALID_LIMIT` (400), and walking on with `.next()` or `for await` reaches
+     * every one.
+     */
+    list(options?: LegalEntityListOptions): Promise<Page<LegalEntity>>;
+    /** Null when no legal entity has that id, or the caller may read none of its stores. */
+    get(id: string, call?: Call): Promise<LegalEntity | null>;
+    /**
+     * Creates a legal entity with no store yet. Refusals: `LEGAL_ENTITY_FIELD_INVALID`,
+     * `INVALID_COUNTRY_CODE`, `INVALID_TIMEZONE` (400).
+     */
+    create(input: CreateLegalEntityInput, call?: Call): Promise<LegalEntity>;
+    /**
+     * Changes the fields given. Refusals: `SHARED_SELLER_NOT_ALLOWED` (403), `ENTITY_NOT_FOUND`
+     * (404), `LEGAL_ENTITY_FIELD_INVALID`, `INVALID_COUNTRY_CODE`, `INVALID_TIMEZONE` (400).
+     */
+    update(id: string, input: UpdateLegalEntityInput, call?: Call): Promise<LegalEntity>;
+    /**
+     * The numbering series the entity's stores share (multi-region B6c): `get` needs `ReadSettings`
+     * and `update` `UpdateSettings`, on every store of the entity (`SHARED_SELLER_NOT_ALLOWED`).
+     */
+    numbering: PlatformLegalEntityNumberingModule;
+}
+export declare const LEGAL_ENTITY_FIELDS = "\n  id\n  name\n  legalName\n  vatNumber\n  vatNumberUk\n  eoriNumber\n  registrationNumber\n  registeredAddressLine1\n  registeredAddressLine2\n  registeredCity\n  registeredPostalCode\n  registeredProvince\n  registeredCountry\n  timezone\n  stores {\n    id\n    code\n  }\n  storeCount\n  editable\n  createdAt\n  updatedAt\n";
+export declare const LEGAL_ENTITIES_QUERY = "\n  query PlatformLegalEntities($options: LegalEntityListOptions) {\n    legalEntities(options: $options) {\n      totalItems\n      items { \n  id\n  name\n  legalName\n  vatNumber\n  vatNumberUk\n  eoriNumber\n  registrationNumber\n  registeredAddressLine1\n  registeredAddressLine2\n  registeredCity\n  registeredPostalCode\n  registeredProvince\n  registeredCountry\n  timezone\n  stores {\n    id\n    code\n  }\n  storeCount\n  editable\n  createdAt\n  updatedAt\n }\n    }\n  }\n";
+export declare const LEGAL_ENTITY_QUERY = "\n  query PlatformLegalEntity($id: ID!) {\n    legalEntity(id: $id) { \n  id\n  name\n  legalName\n  vatNumber\n  vatNumberUk\n  eoriNumber\n  registrationNumber\n  registeredAddressLine1\n  registeredAddressLine2\n  registeredCity\n  registeredPostalCode\n  registeredProvince\n  registeredCountry\n  timezone\n  stores {\n    id\n    code\n  }\n  storeCount\n  editable\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const CREATE_LEGAL_ENTITY_MUTATION = "\n  mutation PlatformCreateLegalEntity($input: CreateLegalEntityInput!) {\n    createLegalEntity(input: $input) { \n  id\n  name\n  legalName\n  vatNumber\n  vatNumberUk\n  eoriNumber\n  registrationNumber\n  registeredAddressLine1\n  registeredAddressLine2\n  registeredCity\n  registeredPostalCode\n  registeredProvince\n  registeredCountry\n  timezone\n  stores {\n    id\n    code\n  }\n  storeCount\n  editable\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const UPDATE_LEGAL_ENTITY_MUTATION = "\n  mutation UpdateLegalEntity($id: ID!, $input: UpdateLegalEntityInput!) {\n    updateLegalEntity(id: $id, input: $input) { \n  id\n  name\n  legalName\n  vatNumber\n  vatNumberUk\n  eoriNumber\n  registrationNumber\n  registeredAddressLine1\n  registeredAddressLine2\n  registeredCity\n  registeredPostalCode\n  registeredProvince\n  registeredCountry\n  timezone\n  stores {\n    id\n    code\n  }\n  storeCount\n  editable\n  createdAt\n  updatedAt\n }\n  }\n";
+/**
+ * The input as the engine declares it, field by field, so a caller spreading a wider object sends
+ * only what the input type has instead of failing validation. A field left out stays out (kept);
+ * `null` is sent as `null` (cleared).
+ */
+export declare function legalEntityInputOf(input: LegalEntityFields & {
+    legalName?: string;
+    name?: string;
+}): Record<string, string | null>;
+export declare function createPlatformLegalEntitiesModule(transport: Transport, config: AdminClientConfig): PlatformLegalEntitiesModule;

package/dist/platform/legal-entities.js

@@ -0,0 +1,126 @@
+import { pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+import { requireHumanSession } from './guard.js';
+import { createPlatformLegalEntityNumberingModule, } from './legal-entity-numbering.js';
+export const LEGAL_ENTITY_FIELDS = /* GraphQL */ `
+  id
+  name
+  legalName
+  vatNumber
+  vatNumberUk
+  eoriNumber
+  registrationNumber
+  registeredAddressLine1
+  registeredAddressLine2
+  registeredCity
+  registeredPostalCode
+  registeredProvince
+  registeredCountry
+  timezone
+  stores {
+    id
+    code
+  }
+  storeCount
+  editable
+  createdAt
+  updatedAt
+`;
+export const LEGAL_ENTITIES_QUERY = /* GraphQL */ `
+  query PlatformLegalEntities($options: LegalEntityListOptions) {
+    legalEntities(options: $options) {
+      totalItems
+      items { ${LEGAL_ENTITY_FIELDS} }
+    }
+  }
+`;
+export const LEGAL_ENTITY_QUERY = /* GraphQL */ `
+  query PlatformLegalEntity($id: ID!) {
+    legalEntity(id: $id) { ${LEGAL_ENTITY_FIELDS} }
+  }
+`;
+export const CREATE_LEGAL_ENTITY_MUTATION = /* GraphQL */ `
+  mutation PlatformCreateLegalEntity($input: CreateLegalEntityInput!) {
+    createLegalEntity(input: $input) { ${LEGAL_ENTITY_FIELDS} }
+  }
+`;
+export const UPDATE_LEGAL_ENTITY_MUTATION = /* GraphQL */ `
+  mutation UpdateLegalEntity($id: ID!, $input: UpdateLegalEntityInput!) {
+    updateLegalEntity(id: $id, input: $input) { ${LEGAL_ENTITY_FIELDS} }
+  }
+`;
+/** The engine's own default; it refuses a page above 100. */
+const DEFAULT_PAGE_SIZE = 50;
+const FIELD_NAMES = [
+    'vatNumber',
+    'vatNumberUk',
+    'eoriNumber',
+    'registrationNumber',
+    'registeredAddressLine1',
+    'registeredAddressLine2',
+    'registeredCity',
+    'registeredPostalCode',
+    'registeredProvince',
+    'registeredCountry',
+    'timezone',
+];
+/**
+ * The input as the engine declares it, field by field, so a caller spreading a wider object sends
+ * only what the input type has instead of failing validation. A field left out stays out (kept);
+ * `null` is sent as `null` (cleared).
+ */
+export function legalEntityInputOf(input) {
+    const out = {};
+    for (const field of ['name', 'legalName', ...FIELD_NAMES]) {
+        const value = input[field];
+        if (value !== undefined)
+            out[field] = value;
+    }
+    return out;
+}
+export function createPlatformLegalEntitiesModule(transport, config) {
+    // Platform-wide, so a SuperAdmin must not need a tenant.
+    const unscoped = (call) => ({ ...call, allowUnscoped: true });
+    const listPage = async (skip, take, options) => {
+        requireHumanSession(config);
+        const variables = {
+            options: { skip, take, ...(options?.term === undefined ? {} : { term: options.term }) },
+        };
+        const data = await transport.graphql({ api: 'admin', query: LEGAL_ENTITIES_QUERY, variables }, unscoped(options));
+        return pageFromVendureList(data.legalEntities, skip, take, (cursor) => listPage(readOffsetCursor(cursor), take, options));
+    };
+    return {
+        numbering: createPlatformLegalEntityNumberingModule(transport, config),
+        async list(options) {
+            // Guarded here as well as per page: a bad cursor must not be reported ahead of the
+            // credential refusal.
+            requireHumanSession(config);
+            const take = options?.limit ?? DEFAULT_PAGE_SIZE;
+            const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return listPage(skip, take, options);
+        },
+        async get(id, call) {
+            requireHumanSession(config);
+            const data = await transport.graphql({ api: 'admin', query: LEGAL_ENTITY_QUERY, variables: { id } }, unscoped(call));
+            return data.legalEntity;
+        },
+        async create(input, call) {
+            requireHumanSession(config);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CREATE_LEGAL_ENTITY_MUTATION,
+                variables: { input: legalEntityInputOf(input) },
+            }, unscoped(call));
+            return data.createLegalEntity;
+        },
+        async update(id, input, call) {
+            requireHumanSession(config);
+            const { name: _ignored, ...fields } = input;
+            const data = await transport.graphql({
+                api: 'admin',
+                query: UPDATE_LEGAL_ENTITY_MUTATION,
+                variables: { id, input: legalEntityInputOf(fields) },
+            }, unscoped(call));
+            return data.updateLegalEntity;
+        },
+    };
+}

package/dist/platform/legal-entity-numbering.d.ts

@@ -0,0 +1,103 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { AdminClientConfig } from '../client.js';
+import type { Call } from '../types.js';
+import type { LegalEntityStore } from './legal-entities.js';
+/**
+ * A legal entity's numbering (multi-region B6c): the series its stores share. One store's invoice
+ * and credit-note numbers, and its AR credit notes where B2B credit is installed, are drawn from
+ * these, whichever store issues the document. A sandbox store numbers on its own rows and is not
+ * one of its stores here.
+ */
+export interface LegalEntityNumbering {
+    /** The legal entity's id. */
+    legalEntityId: string;
+    series: LegalEntityNumberingSeries[];
+    /** The stores sharing the series that the caller may read; `storeCount` counts them all. */
+    stores: LegalEntityStore[];
+    storeCount: number;
+    /**
+     * Whether the caller may change it: a SuperAdmin, or a caller holding `UpdateSettings` on every
+     * store of the entity. Show the series read-only when false.
+     */
+    editable: boolean;
+}
+/** The series the engine numbers: `invoice`, `credit_note`, and `ar_credit_note` with B2B credit. */
+export type LegalEntityNumberingSeriesName = 'invoice' | 'credit_note' | 'ar_credit_note';
+export interface LegalEntityNumberingSeries {
+    series: LegalEntityNumberingSeriesName;
+    /**
+     * False while the entity has no shared series yet. A lone numbering store's first document then
+     * sets it up; with two or more (AR credit notes: two or more that issued), every store's
+     * documents are refused (`LEGAL_ENTITY_NUMBERING_UNSET`) until an `update` sets the series up,
+     * and any `update` does, even an empty one. Every field below is null then.
+     */
+    configured: boolean;
+    prefix: string | null;
+    suffix: string | null;
+    digits: number | null;
+    /** `none`, `short` (`26`) or `full` (`2026`). */
+    yearFormat: string | null;
+    /** Restart at 1 each fiscal year (in the entity's time zone); only with a year in the number. */
+    yearReset: boolean | null;
+    /** The next number the series issues. Read-only: only issuing a document moves it. */
+    nextNumber: number | null;
+    /** The fiscal year the series last restarted in. Read-only. */
+    lastResetYear: number | null;
+    /** `invoice` only: the provider that numbers it; null means each store's own setting. */
+    invoicingProvider: string | null;
+}
+/**
+ * A format change of one series. A field left out is kept; only the fields that differ from the
+ * entity's series count, so on a configured series sending back what was read changes nothing.
+ * On a series with `configured: false` any update, even an empty one, sets the series up.
+ */
+export interface UpdateLegalEntityNumberingInput {
+    series: LegalEntityNumberingSeriesName;
+    /** At most 30 characters, never starting with `TEST-` (`NUMBER_PREFIX_RESERVED`). */
+    prefix?: string;
+    /** At most 30 characters. */
+    suffix?: string;
+    /** A whole number from 3 to 8 (`NUMBERING_DIGITS_INVALID`). */
+    digits?: number;
+    /** `none`, `short` or `full` (`NUMBERING_YEAR_FORMAT_INVALID`). */
+    yearFormat?: 'none' | 'short' | 'full';
+    /** Restart at 1 each fiscal year; it has no effect without a year in the number. */
+    yearReset?: boolean;
+}
+export declare const LEGAL_ENTITY_NUMBERING_FIELDS = "\n  legalEntityId\n  series {\n    series\n    configured\n    prefix\n    suffix\n    digits\n    yearFormat\n    yearReset\n    nextNumber\n    lastResetYear\n    invoicingProvider\n  }\n  stores {\n    id\n    code\n  }\n  storeCount\n  editable\n";
+export declare const LEGAL_ENTITY_NUMBERING_QUERY = "\n  query LegalEntityNumbering($legalEntityId: ID) {\n    legalEntityNumbering(legalEntityId: $legalEntityId) { \n  legalEntityId\n  series {\n    series\n    configured\n    prefix\n    suffix\n    digits\n    yearFormat\n    yearReset\n    nextNumber\n    lastResetYear\n    invoicingProvider\n  }\n  stores {\n    id\n    code\n  }\n  storeCount\n  editable\n }\n  }\n";
+export declare const UPDATE_LEGAL_ENTITY_NUMBERING_MUTATION = "\n  mutation UpdateLegalEntityNumbering($input: UpdateLegalEntityNumberingInput!) {\n    updateLegalEntityNumbering(input: $input) { \n  legalEntityId\n  series {\n    series\n    configured\n    prefix\n    suffix\n    digits\n    yearFormat\n    yearReset\n    nextNumber\n    lastResetYear\n    invoicingProvider\n  }\n  stores {\n    id\n    code\n  }\n  storeCount\n  editable\n }\n  }\n";
+/**
+ * The input as the engine declares it, field by field, so a caller spreading a series it read
+ * (which carries counters and `configured`) sends only the format, and a field left out stays out.
+ */
+export declare function legalEntityNumberingInputOf(input: UpdateLegalEntityNumberingInput, legalEntityId?: string): Record<string, unknown>;
+/**
+ * Refusals the engine answers on `update`: `SHARED_SELLER_NOT_ALLOWED` (403),
+ * `ENTITY_NOT_FOUND` (404), `NUMBERING_SERIES_INVALID`, `NUMBERING_YEAR_FORMAT_INVALID`,
+ * `NUMBERING_DIGITS_INVALID`, `NUMBERING_AFFIX_INVALID` (400), `NUMBER_PREFIX_RESERVED`,
+ * `LEGAL_ENTITY_NUMBERING_PROVIDERS_DIFFER`, `NUMBERING_RESTART_WOULD_REPEAT`,
+ * `NUMBERING_YEAR_FORMAT_UNKNOWN` (422).
+ */
+export interface PlatformLegalEntityNumberingModule {
+    /**
+     * Null when no legal entity has that id, or the caller may read none of its stores;
+     * `SHARED_SELLER_NOT_ALLOWED` (403) when it may read only some of them.
+     */
+    get(legalEntityId: string, call?: Call): Promise<LegalEntityNumbering | null>;
+    /**
+     * Changes the format of one series, on the entity and on every store row of it, in one
+     * transaction, and sets the series up when it has none yet: it then continues past every number
+     * any store issued. Counters change only when an update sets a series up. Safe to repeat.
+     */
+    update(legalEntityId: string, input: UpdateLegalEntityNumberingInput, call?: Call): Promise<LegalEntityNumbering>;
+}
+/** The same, for the ACTIVE store's legal entity: one request each, no id needed. */
+export interface TenantLegalEntityNumberingModule {
+    /** Null on a store with no legal entity, an organization's workspace and the root channel. */
+    get(call?: Call): Promise<LegalEntityNumbering | null>;
+    /** `ENTITY_NOT_FOUND` (404) on a store with no legal entity; otherwise as the platform's. */
+    update(input: UpdateLegalEntityNumberingInput, call?: Call): Promise<LegalEntityNumbering>;
+}
+export declare function createPlatformLegalEntityNumberingModule(transport: Transport, config: AdminClientConfig): PlatformLegalEntityNumberingModule;
+export declare function createTenantLegalEntityNumberingModule(transport: Transport): TenantLegalEntityNumberingModule;

package/dist/platform/legal-entity-numbering.js

@@ -0,0 +1,101 @@
+import { ValidationError } from '@sixtyninecommerce/core';
+import { requireHumanSession } from './guard.js';
+export const LEGAL_ENTITY_NUMBERING_FIELDS = /* GraphQL */ `
+  legalEntityId
+  series {
+    series
+    configured
+    prefix
+    suffix
+    digits
+    yearFormat
+    yearReset
+    nextNumber
+    lastResetYear
+    invoicingProvider
+  }
+  stores {
+    id
+    code
+  }
+  storeCount
+  editable
+`;
+export const LEGAL_ENTITY_NUMBERING_QUERY = /* GraphQL */ `
+  query LegalEntityNumbering($legalEntityId: ID) {
+    legalEntityNumbering(legalEntityId: $legalEntityId) { ${LEGAL_ENTITY_NUMBERING_FIELDS} }
+  }
+`;
+export const UPDATE_LEGAL_ENTITY_NUMBERING_MUTATION = /* GraphQL */ `
+  mutation UpdateLegalEntityNumbering($input: UpdateLegalEntityNumberingInput!) {
+    updateLegalEntityNumbering(input: $input) { ${LEGAL_ENTITY_NUMBERING_FIELDS} }
+  }
+`;
+const INPUT_FIELDS = ['series', 'prefix', 'suffix', 'digits', 'yearFormat', 'yearReset'];
+/**
+ * The input as the engine declares it, field by field, so a caller spreading a series it read
+ * (which carries counters and `configured`) sends only the format, and a field left out stays out.
+ */
+export function legalEntityNumberingInputOf(input, legalEntityId) {
+    const out = {};
+    if (legalEntityId !== undefined)
+        out.legalEntityId = legalEntityId;
+    for (const field of INPUT_FIELDS) {
+        const value = input[field];
+        if (value !== undefined && value !== null)
+            out[field] = value;
+    }
+    return out;
+}
+async function read(transport, legalEntityId, call) {
+    const data = await transport.graphql({
+        api: 'admin',
+        query: LEGAL_ENTITY_NUMBERING_QUERY,
+        variables: legalEntityId === undefined ? {} : { legalEntityId },
+    }, call);
+    return data.legalEntityNumbering;
+}
+async function write(transport, legalEntityId, input, call) {
+    const data = await transport.graphql({
+        api: 'admin',
+        query: UPDATE_LEGAL_ENTITY_NUMBERING_MUTATION,
+        variables: { input: legalEntityNumberingInputOf(input, legalEntityId) },
+    }, call);
+    return data.updateLegalEntityNumbering;
+}
+/**
+ * The platform methods name the entity: without an id the engine would answer for the ACTIVE
+ * store's entity instead, which on a tenant-scoped client is a different one than asked for.
+ */
+function requireLegalEntityId(legalEntityId) {
+    if (typeof legalEntityId !== 'string' || legalEntityId.trim() === '') {
+        throw new ValidationError({
+            code: 'LEGAL_ENTITY_ID_REQUIRED',
+            message: 'platform.legalEntities.numbering needs the legal entity id. For the active store’s ' +
+                'entity use tenant.legalEntity.numbering.',
+            status: 400,
+            service: 'vendure',
+        });
+    }
+    return legalEntityId;
+}
+export function createPlatformLegalEntityNumberingModule(transport, config) {
+    // Platform-wide, so a SuperAdmin must not need a tenant.
+    const unscoped = (call) => ({ ...call, allowUnscoped: true });
+    return {
+        async get(legalEntityId, call) {
+            requireHumanSession(config);
+            return read(transport, requireLegalEntityId(legalEntityId), unscoped(call));
+        },
+        async update(legalEntityId, input, call) {
+            requireHumanSession(config);
+            return write(transport, requireLegalEntityId(legalEntityId), input, unscoped(call));
+        },
+    };
+}
+export function createTenantLegalEntityNumberingModule(transport) {
+    return {
+        get: (call) => read(transport, undefined, call),
+        update: (input, call) => write(transport, undefined, input, call),
+    };
+}

package/dist/platform/organization-membership.d.ts

@@ -0,0 +1,80 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { AdminClientConfig } from '../client.js';
+import type { Call } from '../types.js';
+/** A store's membership of an organization (multi-region spec §5.1, §7.10.3). */
+export interface OrganizationMembership {
+    /** The member store's channel id. */
+    channelId: string;
+    /** The member store. Null once the store no longer exists. */
+    channel: {
+        id: string;
+        code: string;
+    } | null;
+    organizationId: string;
+    /** A free grouping label, such as `EMEA`. Null when none is set. */
+    region: string | null;
+    /** Whether the storefront region switcher lists this store. */
+    listedInRegionSwitcher: boolean;
+    /** ISO-8601 UTC. */
+    joinedAt: string;
+}
+export interface JoinOrganizationInput {
+    /** The organization code, not the `org-` workspace channel code. */
+    organizationCode: string;
+    /** The store's channel id. */
+    channelId: string;
+    /**
+     * A grouping label, at most 64 characters with no line breaks. Omitted keeps
+     * the region a re-join finds (a first join has none); `null` or `''` clears it.
+     */
+    region?: string | null;
+    /**
+     * `true`: the store keeps its own values for every settings group instead of
+     * inheriting the organization's; each group can be switched to inherit later.
+     * On a re-join, a group the store inherits unlocked at that moment starts
+     * from a copy of the organization's values.
+     * Omitted or `false`: it inherits whatever the organization shares, and on a
+     * re-join nothing it already keeps changes. Needs an engine that knows the
+     * field (a `true` sent to an older one is a GraphQL validation error).
+     */
+    keepOwnSettings?: boolean;
+}
+/** The membership half of `admin.platform.organizations`. */
+export interface OrganizationMembershipMethods {
+    /**
+     * Makes a store a member of an organization and answers the membership: the
+     * organization's roles are granted on the store, and the workspace takes on
+     * the store's currencies and languages. Joining the organization the store
+     * is already in answers the same membership (`joinedAt` unchanged), changing
+     * only the region when one is given — so a join whose answer was lost is
+     * safe to repeat. `keepOwnSettings: true` makes the store keep its own
+     * settings (only the groups it does not keep yet are added on a re-join).
+     * There is no way to leave yet. SuperAdmin only.
+     *
+     * Refusals: `ORGANIZATION_MEMBERSHIP_CONFLICT` (409 `ConflictError`: the store
+     * belongs to another organization); `ORGANIZATION_NOT_FOUND` (no organization
+     * has that code) and `ORGANIZATION_MEMBER_STORE_NOT_FOUND` (no store has that
+     * id) (404 `NotFoundError`); `ORGANIZATION_MEMBER_NOT_A_STORE` (the platform's
+     * root channel or an organization's workspace) and
+     * `ORGANIZATION_MEMBER_STORE_CLOSED` (restore the store first) and
+     * `ORGANIZATION_TAX_MODE_MISMATCH` (the store's `pricesIncludeTax` differs
+     * from the organization's: every store of an organization enters prices the
+     * same way; judged on a first join only) (422
+     * `BusinessRuleError`); `ORGANIZATION_MEMBER_REGION_INVALID` (400
+     * `ValidationError`); `FORBIDDEN` (403) for a caller who is not a SuperAdmin.
+     */
+    join(input: JoinOrganizationInput, call?: Call): Promise<OrganizationMembership>;
+    /**
+     * The organization's member stores, oldest member first. A store that no
+     * longer exists is left out. A SuperAdmin reads any organization's with no
+     * tenant; an organization admin reads its own with the workspace channel
+     * (`org-<code>`) as the tenant, and is refused elsewhere with a 403
+     * `PermissionDeniedError` (`FORBIDDEN`, or `ORGANIZATION_ACCESS_DENIED` for
+     * another organization). An unknown id is `ORGANIZATION_NOT_FOUND` (404
+     * `NotFoundError`), not an empty list.
+     */
+    members(organizationId: string, call?: Call): Promise<OrganizationMembership[]>;
+}
+export declare const JOIN_ORGANIZATION_MUTATION = "\n  mutation PlatformJoinOrganization($channelId: ID!, $input: JoinOrganizationInput!) {\n    joinOrganization(channelId: $channelId, input: $input) { \n  channelId\n  channel {\n    id\n    code\n  }\n  organizationId\n  region\n  listedInRegionSwitcher\n  joinedAt\n }\n  }\n";
+export declare const ORGANIZATION_MEMBERS_QUERY = "\n  query PlatformOrganizationMembers($id: ID!) {\n    organization(id: $id) {\n      id\n      members { \n  channelId\n  channel {\n    id\n    code\n  }\n  organizationId\n  region\n  listedInRegionSwitcher\n  joinedAt\n }\n    }\n  }\n";
+export declare function createOrganizationMembershipMethods(transport: Transport, config: AdminClientConfig): OrganizationMembershipMethods;

package/dist/platform/organization-membership.js

@@ -0,0 +1,71 @@
+import { NotFoundError } from '@sixtyninecommerce/core';
+import { requireHumanSession } from './guard.js';
+const MEMBERSHIP_FIELDS = /* GraphQL */ `
+  channelId
+  channel {
+    id
+    code
+  }
+  organizationId
+  region
+  listedInRegionSwitcher
+  joinedAt
+`;
+export const JOIN_ORGANIZATION_MUTATION = /* GraphQL */ `
+  mutation PlatformJoinOrganization($channelId: ID!, $input: JoinOrganizationInput!) {
+    joinOrganization(channelId: $channelId, input: $input) { ${MEMBERSHIP_FIELDS} }
+  }
+`;
+// Through `organization(id)` rather than a query of its own: the engine
+// applies the organization reads' access rule there (a SuperAdmin, or the
+// organization admin in its own workspace), and answers null for an unknown id.
+export const ORGANIZATION_MEMBERS_QUERY = /* GraphQL */ `
+  query PlatformOrganizationMembers($id: ID!) {
+    organization(id: $id) {
+      id
+      members { ${MEMBERSHIP_FIELDS} }
+    }
+  }
+`;
+export function createOrganizationMembershipMethods(transport, config) {
+    // Platform-wide, as in `createPlatformOrganizationsModule`: the opt-in only
+    // matters when the scope is `none`, so an organization admin's workspace
+    // tenant still goes out.
+    const unscoped = (call) => ({ ...call, allowUnscoped: true });
+    return {
+        async join(input, call) {
+            requireHumanSession(config);
+            // The engine reads an ABSENT region as "keep the current one" and null as
+            // "clear it", so an omitted region must stay absent on the wire, never
+            // become null.
+            const joinInput = {
+                organizationCode: input.organizationCode,
+            };
+            if (input.region !== undefined)
+                joinInput.region = input.region;
+            // Only `true` goes on the wire: `false` means what an absent field means, and an engine
+            // older than the field refuses the whole document when it sees one it does not know.
+            if (input.keepOwnSettings === true)
+                joinInput.keepOwnSettings = true;
+            const data = await transport.graphql({
+                api: 'admin',
+                query: JOIN_ORGANIZATION_MUTATION,
+                variables: { channelId: input.channelId, input: joinInput },
+            }, unscoped(call));
+            return data.joinOrganization;
+        },
+        async members(organizationId, call) {
+            requireHumanSession(config);
+            const data = await transport.graphql({ api: 'admin', query: ORGANIZATION_MEMBERS_QUERY, variables: { id: organizationId } }, unscoped(call));
+            if (!data.organization) {
+                throw new NotFoundError({
+                    code: 'ORGANIZATION_NOT_FOUND',
+                    message: `No organization has the id ${organizationId}.`,
+                    status: 404,
+                    service: 'vendure',
+                });
+            }
+            return data.organization.members;
+        },
+    };
+}

package/dist/platform/organization-settings.d.ts

@@ -0,0 +1,33 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { AdminClientConfig } from '../client.js';
+import type { SettingsGroup } from '../tenant/settings-sources.js';
+import type { Call } from '../types.js';
+/** A member store that keeps its own values for one settings group. */
+export interface OrganizationSettingsOverride {
+    /** The member store's channel id. */
+    channelId: string;
+    channelCode: string;
+    group: SettingsGroup | (string & {});
+    /**
+     * When the store started keeping its own values: ISO-8601 in UTC (`…Z`), exactly as the engine
+     * answers it. Compare instants with `Date.parse`; format it in the viewer's time zone only for
+     * display.
+     */
+    overriddenAt: string;
+}
+/** The settings half of `admin.platform.organizations`. */
+export interface OrganizationSettingsMethods {
+    /**
+     * The member stores keeping their own values, one entry per store and group, whether or not
+     * the organization shares that group today — what "Lock for all stores" would take away from
+     * them. Ordered by store code, then by group in catalog order; a store that no longer exists
+     * is left out. A SuperAdmin reads any organization's with no tenant; an organization admin
+     * reads its own with the workspace channel (`org-<code>`) as the tenant and is refused
+     * elsewhere with a 403 `PermissionDeniedError` (`FORBIDDEN`, or `ORGANIZATION_ACCESS_DENIED` for
+     * another organization). A caller who may read the organization but not manage it gets an
+     * empty list. An unknown id is `ORGANIZATION_NOT_FOUND` (404 `NotFoundError`).
+     */
+    settingsOverrides(organizationId: string, call?: Call): Promise<OrganizationSettingsOverride[]>;
+}
+export declare const ORGANIZATION_SETTINGS_OVERRIDES_QUERY = "\n  query PlatformOrganizationSettingsOverrides($id: ID!) {\n    organization(id: $id) {\n      id\n      settingsOverrides {\n        channelId\n        channelCode\n        group\n        overriddenAt\n      }\n    }\n  }\n";
+export declare function createOrganizationSettingsMethods(transport: Transport, config: AdminClientConfig): OrganizationSettingsMethods;