@sixtyninecommerce/admin 0.8.0 → 0.10.0

package/dist/platform/organizations.js

@@ -0,0 +1,180 @@
+import { pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+import { requireHumanSession } from './guard.js';
+import { createOrganizationMembershipMethods, } from './organization-membership.js';
+import { createOrganizationSettingsMethods, } from './organization-settings.js';
+import { createOrganizationSharingModule, } from './organization-sharing.js';
+const ORGANIZATION_FIELDS = /* GraphQL */ `
+  id
+  code
+  name
+  hubChannelId
+  hubChannel {
+    id
+    code
+    pricesIncludeTax
+  }
+  reportingCurrencyCode
+  customerPolicy
+  assortmentMode
+  memberCount
+  createdAt
+  updatedAt
+`;
+const ENTITLEMENT_FIELDS = /* GraphQL */ `
+  id
+  organizationId
+  pluginKey
+  connectedAt
+  connectedByUserId
+  notes
+  createdAt
+  updatedAt
+`;
+export const ORGANIZATIONS_QUERY = /* GraphQL */ `
+  query PlatformOrganizations($options: OrganizationListOptions) {
+    organizations(options: $options) {
+      totalItems
+      items { ${ORGANIZATION_FIELDS} }
+    }
+  }
+`;
+export const ORGANIZATION_QUERY = /* GraphQL */ `
+  query PlatformOrganization($id: ID!) {
+    organization(id: $id) { ${ORGANIZATION_FIELDS} }
+  }
+`;
+export const ORGANIZATION_BY_CODE_QUERY = /* GraphQL */ `
+  query PlatformOrganizationByCode($code: String!) {
+    organizationByCode(code: $code) { ${ORGANIZATION_FIELDS} }
+  }
+`;
+export const CREATE_ORGANIZATION_MUTATION = /* GraphQL */ `
+  mutation PlatformCreateOrganization($input: CreateOrganizationInput!) {
+    createOrganization(input: $input) { ${ORGANIZATION_FIELDS} }
+  }
+`;
+export const REGISTER_ORGANIZATION_WORKSPACE_MUTATION = /* GraphQL */ `
+  mutation PlatformRegisterOrganizationWorkspace($id: ID!) {
+    registerOrganizationWorkspace(id: $id) { ${ORGANIZATION_FIELDS} }
+  }
+`;
+export const UPDATE_ORGANIZATION_MUTATION = /* GraphQL */ `
+  mutation PlatformUpdateOrganization($input: UpdateOrganizationInput!) {
+    updateOrganization(input: $input) { ${ORGANIZATION_FIELDS} }
+  }
+`;
+export const ORGANIZATION_ENTITLEMENTS_QUERY = /* GraphQL */ `
+  query PlatformOrganizationPluginEntitlements($organizationId: ID!) {
+    organizationPluginEntitlements(organizationId: $organizationId) { ${ENTITLEMENT_FIELDS} }
+  }
+`;
+export const SET_ORGANIZATION_ENTITLEMENT_MUTATION = /* GraphQL */ `
+  mutation PlatformSetOrganizationPluginEntitlement(
+    $organizationId: ID!
+    $pluginKey: String!
+    $connected: Boolean!
+    $notes: String
+  ) {
+    setOrganizationPluginEntitlement(
+      organizationId: $organizationId
+      pluginKey: $pluginKey
+      connected: $connected
+      notes: $notes
+    ) { ${ENTITLEMENT_FIELDS} }
+  }
+`;
+/** The server's own default; it caps a page at 100. */
+const DEFAULT_PAGE_SIZE = 50;
+export function createPlatformOrganizationsModule(transport, config) {
+    // Platform-wide, so a SuperAdmin must not need a tenant. An organization
+    // admin passes its workspace channel as the tenant, which this leaves alone:
+    // the opt-in only matters when the scope is `none`.
+    const unscoped = (call) => ({ ...call, allowUnscoped: true });
+    const listPage = async (skip, take, options) => {
+        requireHumanSession(config);
+        const data = await transport.graphql({ api: 'admin', query: ORGANIZATIONS_QUERY, variables: { options: { skip, take } } }, unscoped(options));
+        return pageFromVendureList(data.organizations, skip, take, (cursor) => listPage(readOffsetCursor(cursor), take, options));
+    };
+    return {
+        async create(input, call) {
+            requireHumanSession(config);
+            // Named field by field, so a caller spreading a wider object sends only
+            // what `CreateOrganizationInput` declares instead of failing validation.
+            const variables = {
+                input: {
+                    code: input.code,
+                    name: input.name,
+                    defaultLanguageCode: input.defaultLanguageCode,
+                    defaultCurrencyCode: input.defaultCurrencyCode,
+                    country: input.country,
+                    defaultTaxZoneId: input.defaultTaxZoneId,
+                    defaultShippingZoneId: input.defaultShippingZoneId,
+                    pricesIncludeTax: input.pricesIncludeTax,
+                    reportingCurrencyCode: input.reportingCurrencyCode,
+                },
+            };
+            const data = await transport.graphql({ api: 'admin', query: CREATE_ORGANIZATION_MUTATION, variables }, unscoped(call));
+            return data.createOrganization;
+        },
+        async registerWorkspace(id, call) {
+            requireHumanSession(config);
+            const data = await transport.graphql({ api: 'admin', query: REGISTER_ORGANIZATION_WORKSPACE_MUTATION, variables: { id } }, unscoped(call));
+            return data.registerOrganizationWorkspace;
+        },
+        async update(input, call) {
+            requireHumanSession(config);
+            const variables = {
+                input: {
+                    id: input.id,
+                    name: input.name,
+                    reportingCurrencyCode: input.reportingCurrencyCode,
+                    assortmentMode: input.assortmentMode,
+                },
+            };
+            const data = await transport.graphql({ api: 'admin', query: UPDATE_ORGANIZATION_MUTATION, variables }, unscoped(call));
+            return data.updateOrganization;
+        },
+        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: ORGANIZATION_QUERY, variables: { id } }, unscoped(call));
+            return data.organization;
+        },
+        async getByCode(code, call) {
+            requireHumanSession(config);
+            const data = await transport.graphql({ api: 'admin', query: ORGANIZATION_BY_CODE_QUERY, variables: { code } }, unscoped(call));
+            return data.organizationByCode;
+        },
+        entitlements: {
+            async list(organizationId, call) {
+                requireHumanSession(config);
+                const data = await transport.graphql({ api: 'admin', query: ORGANIZATION_ENTITLEMENTS_QUERY, variables: { organizationId } }, unscoped(call));
+                return data.organizationPluginEntitlements;
+            },
+            async set(input, call) {
+                requireHumanSession(config);
+                const data = await transport.graphql({
+                    api: 'admin',
+                    query: SET_ORGANIZATION_ENTITLEMENT_MUTATION,
+                    variables: {
+                        organizationId: input.organizationId,
+                        pluginKey: input.pluginKey,
+                        connected: input.connected,
+                        notes: input.notes ?? null,
+                    },
+                }, unscoped(call));
+                return data.setOrganizationPluginEntitlement;
+            },
+        },
+        ...createOrganizationMembershipMethods(transport, config),
+        ...createOrganizationSettingsMethods(transport, config),
+        sharing: createOrganizationSharingModule(transport, config),
+    };
+}

package/dist/platform/provision-store.d.ts

@@ -27,6 +27,9 @@ export interface ProvisionStoreInput {
      * Lowercase kebab-case. It is also the object-storage prefix, the CMS key and
      * the order-number namespace, and it can only be changed later by a rename
      * job — so it is worth getting right.
+     *
+     * Codes starting with `org-` are reserved for organizations and refused with
+     * `CHANNEL_CODE_RESERVED` (a `ValidationError`).
      */
     code: string;
     /** Defaults to `commerce`, which is the full webshop. */
@@ -35,6 +38,13 @@ export interface ProvisionStoreInput {
     availableLanguageCodes?: string[];
     defaultCurrencyCode: string;
     availableCurrencyCodes?: string[];
+    /**
+     * Defaults to `true`; with {@link ProvisionStoreInput.organization}, to the
+     * organization's own mode, because every store of an organization enters
+     * prices the same way. A value that differs from the organization's is
+     * refused with `ORGANIZATION_TAX_MODE_MISMATCH` (a {@link BusinessRuleError},
+     * 422) before any run exists.
+     */
     pricesIncludeTax?: boolean;
     /**
      * The store's tax and shipping zones. Send BOTH or NEITHER — a request naming
@@ -57,8 +67,16 @@ export interface ProvisionStoreInput {
     country: string;
     /** IANA zone. Every day-resolution comparison for this store uses it. */
     timezone: string;
-    legalName: string;
+    /**
+     * The legal name of the NEW legal entity this store defines. Required unless
+     * `legalEntity` is set: the server refuses a request with neither
+     * (`VALIDATION_FAILED`, naming `legal_name`). Optional in the type only
+     * because a store created under an existing entity must leave it out.
+     */
+    legalName?: string;
+    /** Of the new legal entity. Left out under `legalEntity`. */
     vatNumber?: string;
+    /** Of the new legal entity. Left out under `legalEntity`. */
     registrationNumber?: string;
     /**
      * Invite a merchant administrator to the new store. SOFT-FAIL: a bounced
@@ -69,19 +87,75 @@ export interface ProvisionStoreInput {
         email: string;
     };
     /**
-     * Reserved. Refused today with `SANDBOX_NOT_AVAILABLE` (a
-     * {@link ValidationError}) until the sandbox channel flag ships.
+     * Provision a SANDBOX store (spec §6.6): the store you point CI and
+     * conformance runs at.
+     *
+     * - Payment providers connect in test mode only: a live account is refused
+     *   `LIVE_CONNECTION_REFUSED` by `payments.providers.completeOnboarding`, and
+     *   so is a live Mollie/Stripe key stored on a payment method.
+     * - ERP and marketing pushes are refused, and the store is left out of
+     *   platform metrics.
+     * - It is purged without the retention checks: a hold placed on it never
+     *   stops its hard delete.
+     * - Apps declared `sandboxOnly` install here and nowhere else, and the
+     *   `sandbox-full` token preset is minted here and nowhere else.
+     * - In production it never emails its customers: every customer-facing
+     *   email (order, account and form confirmations, invoices) is recorded on
+     *   the store's email delivery log as `suppressed_sandbox` instead of sent.
+     *   Staff mail and the store's own addresses on an email still get theirs.
+     *   A development stack delivers everything to its mail catcher.
+     *
+     * Fixed at creation: it can never be cleared, and a store created without it
+     * can never become one (`SANDBOX_IS_PERMANENT`, `SANDBOX_ONLY_AT_PROVISIONING`).
+     * `tenant.capabilities()` reports it as `sandbox`. Defaults to `false`.
      */
     sandbox?: boolean;
-    /** An organization code. Refused with `ORGANIZATIONS_NOT_AVAILABLE`. */
+    /**
+     * An organization code. The new store joins that organization as the run's
+     * LAST step (`organization`), once everything else is built.
+     *
+     * An unknown code is refused with `ORGANIZATION_NOT_FOUND` (a
+     * {@link NotFoundError}, 404) before any run exists, so a typo builds
+     * nothing. If the join itself fails, the store is KEPT, not rolled back: the
+     * run ends `failed` at step `organization` and still carries its `result`,
+     * `wait()` throws `PROVISION_RUN_FAILED` saying so, and the store can be
+     * joined afterwards with `platform.organizations.join` (the Admin API's
+     * `joinOrganization`), which is safe to repeat.
+     */
     organization?: string;
-    /** A Seller id. Refused with `ORGANIZATIONS_NOT_AVAILABLE`. */
+    /**
+     * An existing legal entity's id (`platform.legalEntities`; a Seller id). The
+     * store is created under it and takes its legal name, VAT and registration
+     * numbers; its address, country and time zone stay its own. Left out, the
+     * store defines a new legal entity from `legalName`, `vatNumber` and
+     * `registrationNumber`.
+     *
+     * Every refusal arrives before any run exists, so nothing is built:
+     * - `legalName`, `vatNumber` or `registrationNumber` sent with it:
+     *   `LEGAL_ENTITY_FIELDS_CONFLICT` (a {@link ValidationError}, 400). Change
+     *   the entity's own values with `platform.legalEntities.update` instead.
+     * - an unknown id, an organization workspace's Seller or the platform's own:
+     *   `LEGAL_ENTITY_NOT_FOUND` (a {@link NotFoundError}, 404).
+     * - an entity with no legal name: `LEGAL_ENTITY_INCOMPLETE` (a
+     *   {@link BusinessRuleError}, 422).
+     * - a commerce engine without legal entities (multi-region phase 2):
+     *   `ORGANIZATIONS_NOT_AVAILABLE` (a {@link ValidationError}).
+     *
+     * A sandbox (`sandbox: true`) may be created under an entity live stores
+     * trade under, and the other way round. Its invoices and credit notes are
+     * numbered on its own sequence and start with `TEST-`, so they never take a
+     * number of the entity's series, and it never pays through the entity's live
+     * provider accounts (`LIVE_PAYMENT_REFUSED`).
+     *
+     * A failed run never removes the entity: only the store it was building is
+     * undone.
+     */
     legalEntity?: string;
 }
 export type ProvisionRunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'compensated';
 export type ProvisionStepStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'skipped' | 'compensated';
 export interface ProvisionStep {
-    /** `zones`, `seller`, `channel`, `shipping-methods`, `stock-location`, `roles`, `cms-channel`, `cms-content`, `invite`. */
+    /** `zones`, `seller`, `channel`, `shipping-methods`, `stock-location`, `roles`, `cms-channel`, `cms-content`, `invite`, `organization`. */
     name: string;
     /** `skipped` is a DECISION — the profile did not ask for this object. */
     status: ProvisionStepStatus;
@@ -107,7 +181,10 @@ export interface ProvisionRun {
     profile: string;
     channelCode: string;
     steps: ProvisionStep[];
-    /** Present only on a `succeeded` run. */
+    /**
+     * The store. Present on a `succeeded` run, and on a `failed` run that stopped
+     * at `organization`: that store was built and kept, only the join failed.
+     */
     result?: ProvisionStoreResult;
     /** Non-fatal notes. A merchant invite that bounced is the only one today. */
     warnings: string[];
@@ -121,10 +198,13 @@ export interface PlatformModule {
     /**
      * Build a whole store: seller, channel, zones, shipping methods, stock
      * location, roles, CMS registration and the default CMS menus and forms —
-     * which of them depends on `profile`.
+     * which of them depends on `profile` — and, with `organization`, join it to
+     * that organization.
      *
      * Returns as soon as the run is accepted. The work runs server-side as a saga
      * with recorded compensation, so a failure half-way leaves nothing behind.
+     * The one exception is the organization join, which runs last: when only it
+     * fails, the finished store is kept (see {@link ProvisionStoreInput.organization}).
      *
      * `options.idempotencyKey` makes a retry return the run already in flight
      * instead of starting a second one — send one, and reuse it only for retries

package/dist/platform/provision-store.js

@@ -59,6 +59,18 @@ function resultOf(run) {
     // run into the sentence that follows it.
     const raw = run.error ?? `Provisioning failed at step "${run.step ?? 'unknown'}"`;
     const detail = /[.!?]$/.test(raw.trim()) ? raw.trim() : `${raw.trim()}.`;
+    // A `failed` run that still carries its store stopped at a step that is never
+    // rolled back — the organization join. Nothing is half-built, so the generic
+    // "remove what the message names" would send someone to delete a working
+    // store.
+    if (run.status === 'failed' && run.result) {
+        throw new BusinessRuleError({
+            code: 'PROVISION_RUN_FAILED',
+            message: `${detail} Read the store from platform.provisionRun("${run.id}").result.`,
+            status: 422,
+            service: 'plugins',
+        });
+    }
     throw new BusinessRuleError({
         code: run.status === 'compensated' ? 'PROVISION_RUN_COMPENSATED' : 'PROVISION_RUN_FAILED',
         message: run.status === 'compensated'

package/dist/platform/reports.d.ts

@@ -0,0 +1,46 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { AdminClientConfig } from '../client.js';
+import type { ReportPeriod } from '../reports/index.js';
+import type { Call } from '../types.js';
+export interface FleetReportInput {
+    /**
+     * Two instants WITH an explicit offset. A fleet spans every store, so there
+     * is no single store time zone to read a bare date in: a date is refused
+     * (`INVALID_REPORT_PERIOD`). Omitted = lifetime.
+     */
+    period?: ReportPeriod;
+}
+/** One store's activity. */
+export interface FleetChannelMetric {
+    channelId: string;
+    /** Placed, uncancelled orders in the period (lifetime without one). Carts never count. */
+    orderCount: number;
+    /**
+     * What those orders BILLED (goodwill rounding folded in), in minor units of
+     * `currencyCode` — the store's default currency; orders in another currency
+     * are not in it.
+     */
+    gmvMinor: number;
+    /** Null when the store has no placed order at all. */
+    currencyCode: string | null;
+    /** Lifetime counts, whatever the period. */
+    customerCount: number;
+    productCount: number;
+    /** The store's most recent placed order, ISO-8601 UTC; lifetime. */
+    lastOrderAt: string | null;
+}
+/**
+ * `admin.platform.reports` — cross-store reporting for a human SuperAdmin
+ * session (spec §9.2 `platform` → fleet). An API token or an app credential is
+ * refused BEFORE anything is sent (`PLATFORM_REQUIRES_SESSION`); the server
+ * refuses one anyway (`channelFleetMetrics` is SuperAdmin-only).
+ */
+export interface PlatformReportsModule {
+    /**
+     * Every LIVE store with some activity; a store absent from the list has none.
+     * A sandbox store (`provisionStore({ sandbox: true })`) is never measured.
+     */
+    fleet(input?: FleetReportInput, options?: Call): Promise<FleetChannelMetric[]>;
+}
+export declare const FLEET_QUERY = "\n  query PlatformFleetReport($range: ReportPeriodInput) {\n    channelFleetMetrics(range: $range) {\n      channelId\n      orderCount\n      gmvMinor\n      currencyCode\n      customerCount\n      productCount\n      lastOrderAt\n    }\n  }\n";
+export declare function createPlatformReportsModule(transport: Transport, config: AdminClientConfig): PlatformReportsModule;

package/dist/platform/reports.js

@@ -0,0 +1,31 @@
+import { requireHumanSession } from './guard.js';
+export const FLEET_QUERY = /* GraphQL */ `
+  query PlatformFleetReport($range: ReportPeriodInput) {
+    channelFleetMetrics(range: $range) {
+      channelId
+      orderCount
+      gmvMinor
+      currencyCode
+      customerCount
+      productCount
+      lastOrderAt
+    }
+  }
+`;
+export function createPlatformReportsModule(transport, config) {
+    return {
+        async fleet(input, options) {
+            requireHumanSession(config);
+            const data = await transport.graphql({
+                api: 'admin',
+                query: FLEET_QUERY,
+                variables: {
+                    range: input?.period ? { from: input.period.from, to: input.period.to } : null,
+                },
+            }, 
+            // Cross-store: it is about no one tenant, so it must not need one.
+            { ...options, allowUnscoped: true });
+            return data.channelFleetMetrics;
+        },
+    };
+}

package/dist/platform/server-metrics.d.ts

@@ -0,0 +1,58 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { AdminClientConfig } from '../client.js';
+import type { Call } from '../types.js';
+/** How far back the history series reach. */
+export type ServerMetricsRange = '1h' | '6h' | '24h' | '7d';
+export interface ServerMetricsInput {
+    /** Default `1h`. */
+    range?: ServerMetricsRange;
+}
+export interface ServerMetricPoint {
+    /** Unix epoch milliseconds. */
+    timestamp: number;
+    value: number;
+}
+/**
+ * One host reporting `node_exporter` metrics to the platform's Prometheus. A
+ * reading the host did not report (a down host, a metric its exporter does not
+ * expose) is `null`, never zero.
+ */
+export interface ServerMetrics {
+    /** Prometheus `instance` label (`host:port`) — the stable key. */
+    instance: string;
+    /** The host's own name, else its instance without the port. */
+    name: string;
+    status: 'up' | 'down';
+    cpuPercent: number | null;
+    memoryPercent: number | null;
+    memoryTotalBytes: number | null;
+    /** The root filesystem. */
+    diskPercent: number | null;
+    load1: number | null;
+    cpuCores: number | null;
+    uptimeSeconds: number | null;
+    networkReceiveBytesPerSecond: number | null;
+    networkTransmitBytesPerSecond: number | null;
+    cpuHistory: ServerMetricPoint[];
+    memoryHistory: ServerMetricPoint[];
+    networkReceiveHistory: ServerMetricPoint[];
+    networkTransmitHistory: ServerMetricPoint[];
+}
+export interface ServerMetricsOverview {
+    /** False when this deployment has no Prometheus wired in; `servers` is then empty. */
+    configured: boolean;
+    range: ServerMetricsRange;
+    /** ISO-8601 UTC. The server caches a snapshot for a few seconds. */
+    generatedAt: string;
+    /** Down servers first, then by name. */
+    servers: ServerMetrics[];
+}
+/**
+ * `admin.platform.serverMetrics` — basic health of the platform's own servers,
+ * for a human SuperAdmin session. An API token or an app credential is refused
+ * BEFORE anything is sent (`PLATFORM_REQUIRES_SESSION`).
+ */
+export interface PlatformServerMetricsModule {
+    overview(input?: ServerMetricsInput, options?: Call): Promise<ServerMetricsOverview>;
+}
+export declare function createPlatformServerMetricsModule(transport: Transport, config: AdminClientConfig): PlatformServerMetricsModule;

package/dist/platform/server-metrics.js

@@ -0,0 +1,11 @@
+import { requireHumanSession } from './guard.js';
+export function createPlatformServerMetricsModule(transport, config) {
+    return {
+        async overview(input, options) {
+            requireHumanSession(config);
+            return transport.rest('plugins', { method: 'GET', path: '/server-metrics', query: { range: input?.range } }, 
+            // Cross-tenant: it is about no one store, so it must not need one.
+            { ...options, allowUnscoped: true });
+        },
+    };
+}