@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/shipping/rate-tables.d.ts

@@ -0,0 +1,324 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * A weight-zone rate table: what the `weight-zone-calculator` of a shipping method prices with.
+ * The engine calls it a `ShippingZoneConfig`; a method names it in its calculator argument
+ * `shippingZoneConfigId`.
+ */
+export interface RateTableSummary {
+    id: string;
+    /** Unique within the store. */
+    name: string;
+    /**
+     * Turns a variant's package dimensions into a volumetric weight: length × width × height in cm,
+     * divided by this, is kilograms. An order is charged for the greater of its actual and its
+     * volumetric weight. `0` prices by actual weight only.
+     */
+    volumetricDivisor: number;
+    /** Grams a line weighs when its variant has no package weight; null weighs it as nothing. */
+    defaultWeightGrams: number | null;
+    /** A switched-off table prices nothing: every method using it quotes nothing. */
+    enabled: boolean;
+    /** ISO-8601, UTC. */
+    createdAt: string;
+    /** ISO-8601, UTC. */
+    updatedAt: string;
+}
+/** A place a domestic zone matches by postal code, or an international zone by country. */
+export interface RateTableZoneMember {
+    id: string;
+    /** ISO 3166-1 alpha-2; an international zone's member. */
+    countryCode: string | null;
+    /** First digits of a postal code, start of the range; a domestic zone's member. */
+    postalCodeFrom: string | null;
+    /** End of the range, inclusive. */
+    postalCodeTo: string | null;
+}
+/** One weight tier's price in one currency. */
+export interface RateTableRate {
+    id: string;
+    /** Inclusive. */
+    minWeightGrams: number;
+    /** Exclusive: the tier covers weights from its start up to, not including, this. */
+    maxWeightGrams: number;
+    /**
+     * In minor units: hundredths of {@link currencyCode} for EVERY currency, as the platform stores
+     * all money (€6.95 is 695, ¥1,200 is 120000). In the tax basis the method's calculator says.
+     */
+    price: number;
+    /** ISO 4217. */
+    currencyCode: string;
+}
+/** One zone of a rate table. */
+export interface RateTableZone {
+    id: string;
+    name: string;
+    /**
+     * `domestic` matches its members' postal-code ranges, `international` their countries. A zone
+     * stored before the engine judged the type may hold another word, which prices as
+     * `international`.
+     */
+    type: string;
+    /** Zones are matched in position order; the first that matches the address prices the order. */
+    position: number;
+    members: RateTableZoneMember[];
+    /**
+     * In start-weight order. An order is priced with the tier of its own currency that covers its
+     * weight; without one, with the store's default-currency tier converted at the checkout's
+     * exchange rate; without either, the method quotes nothing.
+     */
+    rates: RateTableRate[];
+    /** ISO-8601, UTC. */
+    createdAt: string;
+    /** ISO-8601, UTC. */
+    updatedAt: string;
+}
+/** A rate table with its zones, as {@link RateTablesModule.get} reads it. */
+export interface RateTable extends RateTableSummary {
+    /** In position order. */
+    zones: RateTableZone[];
+}
+/** A new rate table, as {@link RateTablesModule.create} takes it. It starts switched on. */
+export interface CreateRateTableInput {
+    /** Trimmed; at most 255 characters. */
+    name: string;
+    /** Left out: 5000. See {@link RateTableSummary.volumetricDivisor}. */
+    volumetricDivisor?: number;
+    /** Left out or null: none. See {@link RateTableSummary.defaultWeightGrams}. */
+    defaultWeightGrams?: number | null;
+}
+/** A change to a rate table: a field left out keeps what the table has. */
+export interface UpdateRateTableInput {
+    name?: string;
+    volumetricDivisor?: number;
+    /** `null` clears it. */
+    defaultWeightGrams?: number | null;
+    enabled?: boolean;
+}
+/** How a zone matches an address. See {@link RateTableZone.type}. */
+export type RateTableZoneType = 'domestic' | 'international';
+/** A new zone, as {@link RateTableZonesModule.create} takes it. It starts with no members or rates. */
+export interface CreateRateTableZoneInput {
+    /** Trimmed; at most 255 characters. */
+    name: string;
+    type: RateTableZoneType;
+    /**
+     * Left out: after the table's last zone. A position another zone of the table holds is
+     * refused (`SHIPPING_ZONE_POSITION_TAKEN`); {@link RateTableZonesModule.reorder} moves zones.
+     */
+    position?: number;
+}
+/** A change to a zone: a field left out keeps what the zone has. */
+export interface UpdateRateTableZoneInput {
+    name?: string;
+    /** Refused while the zone has members, which a zone of the other type would never match. */
+    type?: RateTableZoneType;
+    /** Refused (`SHIPPING_ZONE_POSITION_TAKEN`) when another zone of the table holds it. */
+    position?: number;
+}
+/**
+ * One place a zone matches, as {@link RateTableZonesModule.setMembers} takes it: a domestic
+ * zone's member is a postal-code range (no country), an international zone's a country (no
+ * postal codes).
+ */
+export interface RateTableZoneMemberInput {
+    /** ISO 3166-1 alpha-2. */
+    countryCode?: string | null;
+    /** The leading digits of a postal code, start of the range. */
+    postalCodeFrom?: string | null;
+    /** End of the range, inclusive. */
+    postalCodeTo?: string | null;
+}
+/** One weight tier, as {@link RateTableZonesModule.setRates} takes it. */
+export interface RateTableRateInput {
+    /** Inclusive, in grams. */
+    minWeightGrams: number;
+    /** Exclusive, in grams. */
+    maxWeightGrams: number;
+    /** In minor units, as {@link RateTableRate.price}: hundredths for every currency. */
+    price: number;
+    /** ISO 4217. */
+    currencyCode: string;
+}
+/**
+ * `admin.shipping.rateTables.zones`: the zones of the store's rate tables, their members and
+ * their rates. A table or zone of another store is refused as not found (`ENTITY_NOT_FOUND`; a
+ * zone delete `SHIPPING_ZONE_NOT_DELETED`), whatever its id, as a missing one is.
+ *
+ * Besides {@link RateTablesModule}'s `SHIPPING_ZONE_INPUT_INVALID` (here with pointers such as
+ * `/input/type`, `/members/0/postalCodeTo`, `/rates/1/maxWeightGrams` or `/zoneIds/2`, and the
+ * rules `enum`, `pattern`, `not`, `exclusiveMinimum`, `uniqueItems` and `overlap`), the doors
+ * refuse:
+ *
+ * - `SHIPPING_ZONE_POSITION_TAKEN` (`ConflictError`, 409, on `/input/position`): another zone of
+ *   the table is at the position. Zones are matched in position order, first match wins.
+ * - `SHIPPING_ZONE_IN_USE` (`BusinessRuleError`, 422): deleting the last zone of a table a
+ *   shipping method of this store prices with, which would make it quote nothing. The message
+ *   names the methods.
+ *
+ * Every write runs in one transaction: a refused write changes nothing, and a replace
+ * (`setMembers`, `setRates`) refused keeps the zone's previous members or rates.
+ */
+export interface RateTableZonesModule {
+    /**
+     * Add a zone to the store's rate table `tableId`, and answer it as {@link RateTablesModule.get}
+     * reads a zone. Refused `SHIPPING_ZONE_INPUT_INVALID` (a blank or too long name, a type other
+     * than `domestic` or `international`, a negative position), `SHIPPING_ZONE_POSITION_TAKEN`, or
+     * `ENTITY_NOT_FOUND` for a table the store does not have.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    create(tableId: string, input: CreateRateTableZoneInput, options?: Call): Promise<RateTableZone>;
+    /**
+     * Change a zone, and answer it as {@link RateTablesModule.get} reads a zone. Refused as
+     * {@link create} is, for `null` on a field (none can be cleared), for a type change while the
+     * zone has members, or `ENTITY_NOT_FOUND`.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    update(zoneId: string, patch: UpdateRateTableZoneInput, options?: Call): Promise<RateTableZone>;
+    /**
+     * Delete a zone with its members and rates. Refused `SHIPPING_ZONE_IN_USE` for the last zone of
+     * a table a shipping method of this store prices with.
+     *
+     * The engine answers a zone the store does not have (a missing, malformed or another store's
+     * id, or one already deleted) as a result rather than an error; this SDK raises it as
+     * `SHIPPING_ZONE_NOT_DELETED` (`ConflictError`, 409) with the engine's reason.
+     *
+     * @effect destructive
+     * @permission UpdateSettings
+     */
+    delete(zoneId: string, options?: Call): Promise<void>;
+    /**
+     * Put the zones of table `tableId` in the order given; each takes its index as its position.
+     * The list names EVERY zone of the table exactly once: one listed twice, or one left out, is
+     * refused `SHIPPING_ZONE_INPUT_INVALID` (`uniqueItems` on `/zoneIds/<i>`, `required` on
+     * `/zoneIds`), and an id that is not a zone of this table `ENTITY_NOT_FOUND`. Answers the zones
+     * in their new order.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    reorder(tableId: string, zoneIds: string[], options?: Call): Promise<RateTableZone[]>;
+    /**
+     * Replace the zone's members with `members`, and answer them as stored (in the order sent,
+     * trimmed, the country upper-cased). Refused `SHIPPING_ZONE_INPUT_INVALID` per member, on `/members/<i>/<field>`:
+     * a member the zone's type would never match (`not`), a range missing an end (`required`), a
+     * postal code that is not digits (`pattern`), a range that ends before it starts (`minimum`), a
+     * country that is not two letters (`pattern`).
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    setMembers(zoneId: string, members: RateTableZoneMemberInput[], options?: Call): Promise<RateTableZoneMember[]>;
+    /**
+     * Replace the zone's weight tiers with `rates`, and answer them as stored (in the order sent,
+     * the currency trimmed and upper-cased; {@link RateTablesModule.get} reads them in start-weight
+     * order). What every customer whose order the zone prices pays from the next quote on.
+     *
+     * Refused `SHIPPING_ZONE_INPUT_INVALID` per tier, on `/rates/<i>/<field>`: a negative weight or
+     * price (`minimum`), a tier that ends at or before its start (`exclusiveMinimum`), a currency
+     * that is not ISO 4217 (`enum`), and, within one currency, two tiers with the same start
+     * (`uniqueItems`) or sharing weights (`overlap`). Gaps are allowed: a weight in a gap gets no
+     * quote.
+     *
+     * @effect money
+     * @permission UpdateSettings
+     */
+    setRates(zoneId: string, rates: RateTableRateInput[], options?: Call): Promise<RateTableRate[]>;
+}
+/**
+ * `admin.shipping.rateTables`: the store's weight-zone rate tables (headless spec §9.2
+ * `shipping`, "zones, calculator config"). Scoped to the store the client is on: another
+ * store's table is not listed, reads as null and is refused as not found, whatever its id.
+ *
+ * Every refusal of the engine's rate-table doors carries a code:
+ *
+ * - `SHIPPING_ZONE_INPUT_INVALID` (`ValidationError`, 400): what was sent cannot be stored.
+ *   `error.details[]` names EVERY problem of the save at once, each with `field`, a JSON Pointer
+ *   into the arguments (`/input/name`, `/input/volumetricDivisor`), and `code`, the rule broken
+ *   (`required`, `type`, `minimum`, `maximum`, `maxLength`). The SDK raises the same code, with
+ *   the same pointers, for a value it cannot send at all (not a string, not a whole number
+ *   GraphQL's `Int` carries), before anything leaves.
+ * - `SHIPPING_ZONE_CONFIG_NAME_TAKEN` (`ConflictError`, 409): another table of this store has
+ *   the name (`details[0].field` is `/input/name`). Another store's names are free.
+ * - `SHIPPING_ZONE_CONFIG_IN_USE` (`BusinessRuleError`, 422): a delete of a table a shipping
+ *   method of this store prices with. The message names the methods (three, then "and N more");
+ *   the engine also lists them as `extensions.shippingMethods` (`{ id, code, name }`), which this
+ *   SDK does not lift onto the error. Nothing is deleted.
+ * - `ENTITY_NOT_FOUND` (`NotFoundError`, 404): an update of a table the store does not have (a
+ *   missing, malformed or another store's id read alike).
+ * - `FORBIDDEN` (`PermissionDeniedError`, 403): reads need `ReadSettings`, writes
+ *   `UpdateSettings` (a create and a delete too).
+ *
+ * Every write runs in one transaction: a refused write changes nothing.
+ */
+export interface RateTablesModule {
+    /**
+     * Every rate table of the store, switched off or not, newest first. Not paged: a store has a
+     * handful.
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    list(options?: Call): Promise<RateTableSummary[]>;
+    /**
+     * One rate table with its zones, their members and rates, or `null` when the store has no
+     * such table (a missing, malformed or another store's id read alike).
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    get(id: string, options?: Call): Promise<RateTable | null>;
+    /**
+     * Add a rate table to the store, switched on and with no zones, and answer it as {@link get}
+     * reads it. Refused `SHIPPING_ZONE_INPUT_INVALID` (a blank or too long name, a negative
+     * divisor or default weight) or `SHIPPING_ZONE_CONFIG_NAME_TAKEN`.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    create(input: CreateRateTableInput, options?: Call): Promise<RateTable>;
+    /**
+     * Change a rate table, and answer it as {@link get} reads it. Every method pricing with it
+     * quotes by the change from the next quote on, and switching it off makes them quote nothing
+     * (allowed: it is the switch's purpose, and it is undone by switching it back on).
+     *
+     * Refused `SHIPPING_ZONE_INPUT_INVALID` (as {@link create}, and `null` for the name, the
+     * divisor or `enabled`, which cannot be cleared), `SHIPPING_ZONE_CONFIG_NAME_TAKEN` or
+     * `ENTITY_NOT_FOUND`.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    update(id: string, patch: UpdateRateTableInput, options?: Call): Promise<RateTable>;
+    /**
+     * Delete a rate table with its zones, members and rates. Refused
+     * `SHIPPING_ZONE_CONFIG_IN_USE` while a shipping method of this store prices with it (give the
+     * method another table, or delete it, first).
+     *
+     * The engine answers a table the store does not have (a missing, malformed or another store's
+     * id, or one already deleted) as a result rather than an error; this SDK raises it as
+     * `SHIPPING_ZONE_CONFIG_NOT_DELETED` (`ConflictError`, 409) with the engine's reason.
+     *
+     * @effect destructive
+     * @permission UpdateSettings
+     */
+    delete(id: string, options?: Call): Promise<void>;
+    /** The zones of the store's tables, their members and their rates. */
+    zones: RateTableZonesModule;
+}
+export declare const RATE_TABLES_QUERY = "\n  query StoreRateTables {\n    shippingZoneConfigs { \n  id\n  name\n  volumetricDivisor\n  defaultWeightGrams\n  enabled\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const RATE_TABLE_QUERY = "\n  query StoreRateTable($id: ID!) {\n    shippingZoneConfig(id: $id) { \n  \n  id\n  name\n  volumetricDivisor\n  defaultWeightGrams\n  enabled\n  createdAt\n  updatedAt\n\n  zones { \n  id\n  name\n  type\n  position\n  members { \n  id\n  countryCode\n  postalCodeFrom\n  postalCodeTo\n }\n  rates { \n  id\n  minWeightGrams\n  maxWeightGrams\n  price\n  currencyCode\n }\n  createdAt\n  updatedAt\n }\n }\n  }\n";
+export declare const CREATE_RATE_TABLE_MUTATION = "\n  mutation CreateStoreRateTable($input: CreateShippingZoneConfigInput!) {\n    createShippingZoneConfig(input: $input) { \n  \n  id\n  name\n  volumetricDivisor\n  defaultWeightGrams\n  enabled\n  createdAt\n  updatedAt\n\n  zones { \n  id\n  name\n  type\n  position\n  members { \n  id\n  countryCode\n  postalCodeFrom\n  postalCodeTo\n }\n  rates { \n  id\n  minWeightGrams\n  maxWeightGrams\n  price\n  currencyCode\n }\n  createdAt\n  updatedAt\n }\n }\n  }\n";
+export declare const UPDATE_RATE_TABLE_MUTATION = "\n  mutation UpdateStoreRateTable($id: ID!, $input: UpdateShippingZoneConfigInput!) {\n    updateShippingZoneConfig(id: $id, input: $input) { \n  \n  id\n  name\n  volumetricDivisor\n  defaultWeightGrams\n  enabled\n  createdAt\n  updatedAt\n\n  zones { \n  id\n  name\n  type\n  position\n  members { \n  id\n  countryCode\n  postalCodeFrom\n  postalCodeTo\n }\n  rates { \n  id\n  minWeightGrams\n  maxWeightGrams\n  price\n  currencyCode\n }\n  createdAt\n  updatedAt\n }\n }\n  }\n";
+export declare const DELETE_RATE_TABLE_MUTATION = "\n  mutation DeleteStoreRateTable($id: ID!) {\n    deleteShippingZoneConfig(id: $id) {\n      result\n      message\n    }\n  }\n";
+export declare const CREATE_RATE_TABLE_ZONE_MUTATION = "\n  mutation CreateStoreRateTableZone($configId: ID!, $input: CreateShippingZoneInput!) {\n    createShippingZone(configId: $configId, input: $input) { \n  id\n  name\n  type\n  position\n  members { \n  id\n  countryCode\n  postalCodeFrom\n  postalCodeTo\n }\n  rates { \n  id\n  minWeightGrams\n  maxWeightGrams\n  price\n  currencyCode\n }\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const UPDATE_RATE_TABLE_ZONE_MUTATION = "\n  mutation UpdateStoreRateTableZone($id: ID!, $input: UpdateShippingZoneInput!) {\n    updateShippingZone(id: $id, input: $input) { \n  id\n  name\n  type\n  position\n  members { \n  id\n  countryCode\n  postalCodeFrom\n  postalCodeTo\n }\n  rates { \n  id\n  minWeightGrams\n  maxWeightGrams\n  price\n  currencyCode\n }\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DELETE_RATE_TABLE_ZONE_MUTATION = "\n  mutation DeleteStoreRateTableZone($id: ID!) {\n    deleteShippingZone(id: $id) {\n      result\n      message\n    }\n  }\n";
+export declare const REORDER_RATE_TABLE_ZONES_MUTATION = "\n  mutation ReorderStoreRateTableZones($configId: ID!, $zoneIds: [ID!]!) {\n    reorderShippingZones(configId: $configId, zoneIds: $zoneIds) { \n  id\n  name\n  type\n  position\n  members { \n  id\n  countryCode\n  postalCodeFrom\n  postalCodeTo\n }\n  rates { \n  id\n  minWeightGrams\n  maxWeightGrams\n  price\n  currencyCode\n }\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const SET_RATE_TABLE_ZONE_MEMBERS_MUTATION = "\n  mutation SetStoreRateTableZoneMembers($zoneId: ID!, $members: [ShippingZoneMemberInput!]!) {\n    setShippingZoneMembers(zoneId: $zoneId, members: $members) { \n  id\n  countryCode\n  postalCodeFrom\n  postalCodeTo\n }\n  }\n";
+export declare const SET_RATE_TABLE_ZONE_RATES_MUTATION = "\n  mutation SetStoreRateTableZoneRates($zoneId: ID!, $rates: [ShippingRateInput!]!) {\n    setShippingRates(zoneId: $zoneId, rates: $rates) { \n  id\n  minWeightGrams\n  maxWeightGrams\n  price\n  currencyCode\n }\n  }\n";
+export declare function createRateTablesModule(transport: Transport): RateTablesModule;