@sixtyninecommerce/admin 0.11.0 → 0.13.0

package/dist/platform/email-gateways.d.ts

@@ -0,0 +1,165 @@
+import type { Transport } from '@sixtyninecommerce/core';
+import type { AdminClientConfig } from '../client.js';
+import type { Call } from '../types.js';
+/** How a gateway sends: an SMTP server, or the sixtynine.email HTTP API. Fixed at creation. */
+export type EmailGatewayType = 'smtp' | 'sixtynine_email';
+/**
+ * A store's email gateway: the way its transactional email leaves the platform. One per store at
+ * most; a store without one sends through the platform's default sender.
+ *
+ * Credentials (the SMTP password, the sixtynine.email API key) are write-only and never read back.
+ */
+export interface EmailGateway {
+    id: string;
+    /** The store (channel id) it sends for. */
+    channelId: string;
+    type: EmailGatewayType;
+    name: string;
+    /** SMTP only; `null` on a sixtynine.email gateway. */
+    host: string | null;
+    /** SMTP only; `null` on a sixtynine.email gateway. */
+    port: number | null;
+    /** SMTP only; `null` for an unauthenticated relay or a sixtynine.email gateway. */
+    username: string | null;
+    fromAddress: string;
+    fromName: string;
+    /**
+     * SMTP only: `tls` (TLS from the first byte, usually port 465), `starttls` (a plain connection
+     * that must upgrade to TLS, usually port 587) or `none`. `null` on a sixtynine.email gateway.
+     */
+    encryption: string | null;
+    /** sixtynine.email only: the API's address, such as `https://sixtynine.email`. */
+    apiUrl: string | null;
+    /** A disabled gateway is skipped: its store sends through the platform's default sender. */
+    enabled: boolean;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+    /** ISO-8601 UTC. */
+    updatedAt: string;
+}
+/**
+ * A new gateway. `type` decides which fields apply: an SMTP gateway (the default) needs `host` and
+ * `password`; a sixtynine.email gateway needs `apiKey`. The other type's fields are ignored.
+ */
+export interface CreateEmailGatewayInput {
+    channelId: string;
+    /** Default `smtp`. */
+    type?: EmailGatewayType;
+    name: string;
+    host?: string;
+    /** 1–65535; default 587. */
+    port?: number;
+    username?: string;
+    /** Write-only. */
+    password?: string;
+    /**
+     * `tls`, `starttls` or `none`. Left out: `tls` on port 465, `starttls` on any other. Any other
+     * letter case of `TLS`/`STARTTLS` is stored by the port (465 → `tls`, else `starttls`).
+     */
+    encryption?: string;
+    /**
+     * An https:// address on one of the platform's sixtynine.email hosts (such as
+     * `https://sixtynine.email`), with no user name, query or fragment: the API key is sent there.
+     * Left out, none is stored and the gateway sends nothing until one is set.
+     */
+    apiUrl?: string;
+    /** Write-only. */
+    apiKey?: string;
+    fromAddress: string;
+    fromName: string;
+}
+/**
+ * A change to a gateway. A field left out keeps what the gateway has; `password` and `apiKey`
+ * left out or empty keep the stored credential. The type cannot change: the SMTP fields are
+ * ignored on a sixtynine.email gateway, and `apiUrl`/`apiKey` on an SMTP one.
+ */
+export interface UpdateEmailGatewayInput {
+    /** Moves the gateway to another store. */
+    channelId?: string;
+    name?: string;
+    host?: string;
+    port?: number;
+    /** `null` clears it (an unauthenticated relay). */
+    username?: string | null;
+    password?: string;
+    encryption?: string;
+    /** `null` clears it: the gateway then sends nothing. */
+    apiUrl?: string | null;
+    apiKey?: string;
+    fromAddress?: string;
+    fromName?: string;
+    enabled?: boolean;
+}
+/**
+ * `admin.platform.emailGateways` — the stores' email gateways, for platform staff (spec §9.2
+ * `platform`). Gateways of every store, so no tenant is needed on the client.
+ *
+ * Every method needs a human SuperAdmin session: an API token or an app credential is refused
+ * with `PLATFORM_REQUIRES_SESSION` (`PermissionDeniedError`, 403) BEFORE anything is sent, and a
+ * session without SuperAdmin is refused by the engine (`FORBIDDEN`).
+ *
+ * **Coded refusals** (GraphQL errors mapped by `core`):
+ * - `EMAIL_GATEWAY_INPUT_INVALID` → `ValidationError` (400): a value the gateway cannot use. Every
+ *   problem of one save comes back at once in `details[]` (`field` names the input property, e.g.
+ *   `apiUrl`), and no refusal repeats a value it was sent (a password put in the wrong field
+ *   never comes back).
+ * - `EMAIL_GATEWAY_NOT_FOUND` → `NotFoundError` (404): no gateway has that id.
+ * - `EMAIL_GATEWAY_CHANNEL_TAKEN` → `ConflictError` (409): the store already has a gateway.
+ * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` → `BusinessRuleError` (422): a workspace's channel is
+ *   not a store; moving a gateway there, enabling one there or storing a credential on it is
+ *   refused.
+ * - `EMAIL_GATEWAY_TEST_FAILED` → `BusinessRuleError` (422): see {@link test}.
+ * - `EMAIL_GATEWAY_TEST_NOT_SUPPORTED` → `BusinessRuleError` (422): see {@link test}.
+ */
+export interface PlatformEmailGatewaysModule {
+    /**
+     * Every store's gateway, newest first.
+     *
+     * @effect read
+     */
+    list(options?: Call): Promise<EmailGateway[]>;
+    /**
+     * One gateway, or `null` when no gateway has that id.
+     *
+     * @effect read
+     */
+    get(id: string, options?: Call): Promise<EmailGateway | null>;
+    /**
+     * Create a store's gateway, enabled, and answer it as read.
+     *
+     * @effect write
+     */
+    create(input: CreateEmailGatewayInput, options?: Call): Promise<EmailGateway>;
+    /**
+     * Change a gateway, and answer it as read.
+     *
+     * @effect write
+     */
+    update(id: string, patch: UpdateEmailGatewayInput, options?: Call): Promise<EmailGateway>;
+    /**
+     * Delete a gateway. Its store then sends through the platform's default sender.
+     *
+     * @effect destructive
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /**
+     * Check that an SMTP gateway's server takes a connection with its stored settings and
+     * credentials. No email is sent. Resolves when the check passed.
+     *
+     * - `EMAIL_GATEWAY_TEST_FAILED`: the server refused or could not be reached. The message names
+     *   the step that failed (TLS handshake, user name or password, host name, timeout,
+     *   connection), never the server's own reply.
+     * - `EMAIL_GATEWAY_TEST_NOT_SUPPORTED`: a sixtynine.email gateway; the check is SMTP-only.
+     * - `EMAIL_GATEWAY_NOT_FOUND`: no gateway has that id.
+     *
+     * @effect read
+     */
+    test(id: string, options?: Call): Promise<void>;
+}
+export declare const EMAIL_GATEWAYS_QUERY = "\n  query PlatformEmailGateways {\n    emailGateways { \n  id\n  channelId\n  type\n  name\n  host\n  port\n  username\n  fromAddress\n  fromName\n  encryption\n  apiUrl\n  enabled\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const EMAIL_GATEWAY_QUERY = "\n  query PlatformEmailGateway($id: ID!) {\n    emailGateway(id: $id) { \n  id\n  channelId\n  type\n  name\n  host\n  port\n  username\n  fromAddress\n  fromName\n  encryption\n  apiUrl\n  enabled\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const CREATE_EMAIL_GATEWAY_MUTATION = "\n  mutation PlatformCreateEmailGateway($input: CreateEmailGatewayInput!) {\n    createEmailGateway(input: $input) { \n  id\n  channelId\n  type\n  name\n  host\n  port\n  username\n  fromAddress\n  fromName\n  encryption\n  apiUrl\n  enabled\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const UPDATE_EMAIL_GATEWAY_MUTATION = "\n  mutation PlatformUpdateEmailGateway($id: ID!, $input: UpdateEmailGatewayInput!) {\n    updateEmailGateway(id: $id, input: $input) { \n  id\n  channelId\n  type\n  name\n  host\n  port\n  username\n  fromAddress\n  fromName\n  encryption\n  apiUrl\n  enabled\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DELETE_EMAIL_GATEWAY_MUTATION = "\n  mutation PlatformDeleteEmailGateway($id: ID!) {\n    deleteEmailGateway(id: $id) { result }\n  }\n";
+export declare const TEST_EMAIL_GATEWAY_MUTATION = "\n  mutation PlatformTestEmailGateway($id: ID!) {\n    testEmailGateway(id: $id)\n  }\n";
+export declare function createPlatformEmailGatewaysModule(transport: Transport, config: AdminClientConfig): PlatformEmailGatewaysModule;

package/dist/platform/email-gateways.js

@@ -0,0 +1,78 @@
+import { fieldOf } from '../catalog/types.js';
+import { requireHumanSession } from './guard.js';
+const GATEWAY_FIELDS = /* GraphQL */ `
+  id
+  channelId
+  type
+  name
+  host
+  port
+  username
+  fromAddress
+  fromName
+  encryption
+  apiUrl
+  enabled
+  createdAt
+  updatedAt
+`;
+export const EMAIL_GATEWAYS_QUERY = /* GraphQL */ `
+  query PlatformEmailGateways {
+    emailGateways { ${GATEWAY_FIELDS} }
+  }
+`;
+export const EMAIL_GATEWAY_QUERY = /* GraphQL */ `
+  query PlatformEmailGateway($id: ID!) {
+    emailGateway(id: $id) { ${GATEWAY_FIELDS} }
+  }
+`;
+export const CREATE_EMAIL_GATEWAY_MUTATION = /* GraphQL */ `
+  mutation PlatformCreateEmailGateway($input: CreateEmailGatewayInput!) {
+    createEmailGateway(input: $input) { ${GATEWAY_FIELDS} }
+  }
+`;
+export const UPDATE_EMAIL_GATEWAY_MUTATION = /* GraphQL */ `
+  mutation PlatformUpdateEmailGateway($id: ID!, $input: UpdateEmailGatewayInput!) {
+    updateEmailGateway(id: $id, input: $input) { ${GATEWAY_FIELDS} }
+  }
+`;
+export const DELETE_EMAIL_GATEWAY_MUTATION = /* GraphQL */ `
+  mutation PlatformDeleteEmailGateway($id: ID!) {
+    deleteEmailGateway(id: $id) { result }
+  }
+`;
+export const TEST_EMAIL_GATEWAY_MUTATION = /* GraphQL */ `
+  mutation PlatformTestEmailGateway($id: ID!) {
+    testEmailGateway(id: $id)
+  }
+`;
+export function createPlatformEmailGatewaysModule(transport, config) {
+    // Gateways of every store: no store is involved, so no tenant is needed (as `platform.tax`).
+    const unscoped = (call) => ({ ...call, allowUnscoped: true });
+    return {
+        async list(options) {
+            requireHumanSession(config);
+            return fieldOf(transport, EMAIL_GATEWAYS_QUERY, 'emailGateways', {}, unscoped(options));
+        },
+        async get(id, options) {
+            requireHumanSession(config);
+            return fieldOf(transport, EMAIL_GATEWAY_QUERY, 'emailGateway', { id }, unscoped(options));
+        },
+        async create(input, options) {
+            requireHumanSession(config);
+            return fieldOf(transport, CREATE_EMAIL_GATEWAY_MUTATION, 'createEmailGateway', { input }, unscoped(options));
+        },
+        async update(id, patch, options) {
+            requireHumanSession(config);
+            return fieldOf(transport, UPDATE_EMAIL_GATEWAY_MUTATION, 'updateEmailGateway', { id, input: patch }, unscoped(options));
+        },
+        async delete(id, options) {
+            requireHumanSession(config);
+            await fieldOf(transport, DELETE_EMAIL_GATEWAY_MUTATION, 'deleteEmailGateway', { id }, unscoped(options));
+        },
+        async test(id, options) {
+            requireHumanSession(config);
+            await fieldOf(transport, TEST_EMAIL_GATEWAY_MUTATION, 'testEmailGateway', { id }, unscoped(options));
+        },
+    };
+}

package/dist/platform/tax.d.ts

@@ -21,8 +21,10 @@ export interface UpdateTaxCategoryInput {
 export interface CreateTaxRateInput {
     name: string;
     /**
-     * A percentage: `21` is 21 %. Not money. The engine keeps two decimals (`5.5`, `20.75`), so
-     * a third one is rounded when it is stored; the answer carries the stored value.
+     * A percentage from 0 to 100, both included: `21` is 21 %. Not money. The engine keeps two
+     * decimals (`5.5`, `20.75`), so a third one is rounded when it is stored; the answer carries
+     * the stored value. A value outside 0–100 is refused as sent, before any rounding
+     * (`TAX_RATE_VALUE_INVALID`).
      */
     value: number;
     /** A disabled rate is never applied. Required: a rate is applied from the moment it exists. */
@@ -113,6 +115,10 @@ export interface PlatformTaxRatesModule {
      *
      * - `INVALID_TAX_RATE_INPUT` (`ValidationError`, 400): a missing name, category, zone or
      *   `enabled`, or a value that is not a finite number, refused here before anything is sent.
+     * - `TAX_RATE_VALUE_INVALID` (`ValidationError`, 400): a value below 0 or above 100. Refused
+     *   here before anything is sent, and by the engine for any other caller, with the same code
+     *   and `details[0].field` `/input/value` (`code` `minimum` or `maximum`), so a form can put
+     *   the sentence on the rate field whichever side refused it.
      * - `ENTITY_NOT_FOUND` (`NotFoundError`, 404): the category, zone or customer group does not
      *   exist.
      *
@@ -125,7 +131,9 @@ export interface PlatformTaxRatesModule {
     /**
      * Change a tax rate, and answer it as read. Refused as {@link create} is, plus
      * `INVALID_TAX_RATE_INPUT` for `customerGroupId: null` (see {@link UpdateTaxRateInput}) and
-     * `ENTITY_NOT_FOUND` for an unknown rate.
+     * `ENTITY_NOT_FOUND` for an unknown rate. Only a value the patch SENDS is held to 0–100: a
+     * rate stored outside it before the bound existed can still be renamed or switched off
+     * without one.
      *
      * @effect money
      */

package/dist/platform/tax.js

@@ -36,6 +36,33 @@ const isObject = (value) => typeof value === 'object' && value !== null && !Arra
 const refusal = (code) => (message) => new ValidationError({ code, message, status: 400, service: 'vendure' });
 const categoryRefusal = refusal('INVALID_TAX_CATEGORY_INPUT');
 const rateRefusal = refusal('INVALID_TAX_RATE_INPUT');
+/** The bounds of a rate's percentage; the engine holds every caller to the same ones. */
+const TAX_RATE_MIN_PERCENT = 0;
+const TAX_RATE_MAX_PERCENT = 100;
+/**
+ * The engine's own refusal of a value outside 0–100 % (`TAX_RATE_VALUE_INVALID`), word for word,
+ * with the detail on `/input/value` the engine answers, so a caller cannot tell which side
+ * refused it.
+ */
+function rateValueOutOfRange(value) {
+    const below = value < TAX_RATE_MIN_PERCENT;
+    const range = `from ${String(TAX_RATE_MIN_PERCENT)} to ${String(TAX_RATE_MAX_PERCENT)}`;
+    return new ValidationError({
+        code: 'TAX_RATE_VALUE_INVALID',
+        message: below
+            ? `A tax rate cannot be below ${String(TAX_RATE_MIN_PERCENT)} %: ${String(value)} % was sent. Enter a percentage ${range}.`
+            : `A tax rate cannot be above ${String(TAX_RATE_MAX_PERCENT)} %: ${String(value)} % was sent. Enter a percentage ${range}.`,
+        status: 400,
+        service: 'vendure',
+        details: [
+            {
+                field: '/input/value',
+                code: below ? 'minimum' : 'maximum',
+                message: `Enter a rate ${range}.`,
+            },
+        ],
+    });
+}
 function requireId(id, what, refuse) {
     if (typeof id !== 'string' || id.trim() === '')
         throw refuse(`${what} must be an id.`);
@@ -72,6 +99,9 @@ function rateInput(input, creating) {
         if (typeof input.value !== 'number' || !Number.isFinite(input.value)) {
             throw rateRefusal('value must be a finite number: the percentage, 21 for 21 %.');
         }
+        if (input.value < TAX_RATE_MIN_PERCENT || input.value > TAX_RATE_MAX_PERCENT) {
+            throw rateValueOutOfRange(input.value);
+        }
         out.value = input.value;
     }
     if (input.enabled !== undefined || creating) {

package/dist/pos/exchanges.d.ts

@@ -86,7 +86,12 @@ export interface PosExchangeResult {
     carries: PosExchangeCarry[];
     refunds: PosReturnRefund[];
     cashPaidOut: number;
-    /** What the cart still owes: 0. Complete it with `sale.complete`. */
+    /**
+     * What the cart still owes after the credit: 0, unless a card is being charged on it or a
+     * payment link is open, which the exchange holds back (it never carries credit over money in
+     * flight). Complete the sale with `sale.complete` once that money lands; a completion while
+     * money is still owed is refused `POS_SALE_NOT_COVERED`.
+     */
     remaining: number;
     complete: boolean;
 }