@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/geo/index.d.ts

@@ -0,0 +1,119 @@
+import type { Page, Transport } from '@sixtyninecommerce/core';
+import type { Call, ListOptions } from '../types.js';
+/**
+ * A country. Countries are PLATFORM-WIDE: every store reads the same table, and only a
+ * SuperAdmin changes it.
+ */
+export interface Country {
+    id: string;
+    /** In the language of the request. */
+    name: string;
+    /** ISO 3166-1 alpha-2, upper case. */
+    code: string;
+    /** A disabled country is kept for history; checkout and addresses refuse it. */
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A region inside a zone: today always a country (`type: 'country'`). */
+export interface ZoneMember {
+    id: string;
+    name: string;
+    code: string;
+    enabled: boolean;
+    type: string;
+}
+/** A tax or shipping zone: a named set of countries, platform-wide like the countries. */
+export interface Zone {
+    id: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A zone with the countries in it. */
+export interface ZoneWithMembers extends Zone {
+    members: ZoneMember[];
+}
+/** Options for {@link GeoZonesModule.list}. */
+export interface ZoneListOptions extends ListOptions {
+    /** Also select each zone's members (the countries in it). Defaults to false. */
+    members?: boolean;
+}
+export interface GeoCountriesModule {
+    /**
+     * The platform's countries, in id order.
+     *
+     * A `Page`: walk it (`for await`, or `.next()` until null) for the COMPLETE list. Nothing is cut
+     * at a fixed size; every following page keeps the same order and per-call options.
+     *
+     * @effect read
+     */
+    list(options?: ListOptions): Promise<Page<Country>>;
+}
+export interface GeoZonesModule {
+    /**
+     * The platform's zones, in id order, with their members when `members` is true.
+     *
+     * A `Page`: walk it (`for await`, or `.next()` until null) for the COMPLETE list. Nothing is cut
+     * at a fixed size; every following page keeps the same order, `members` and per-call options.
+     *
+     * @effect read
+     */
+    list(options: ZoneListOptions & {
+        members: true;
+    }): Promise<Page<ZoneWithMembers>>;
+    /**
+     * The platform's zones, in id order, without their members. A complete list when walked.
+     *
+     * @effect read
+     */
+    list(options?: ZoneListOptions): Promise<Page<Zone>>;
+    /**
+     * One zone with its members, or null when no zone has that id. An id that is not in the
+     * platform's id format at all is refused by the engine (`ENTITY_NOT_FOUND`, a `NotFoundError`).
+     *
+     * @effect read
+     */
+    get(id: string, options?: Call): Promise<ZoneWithMembers | null>;
+}
+/**
+ * Countries and zones (spec §9.2, ruling G128). Platform-wide reads: any store's client answers
+ * the same lists. Reading needs `ReadCountry` / `ReadZone`, which every store role holds; a
+ * SuperAdmin writes them through `platform.geo`.
+ */
+export interface GeoModule {
+    countries: GeoCountriesModule;
+    zones: GeoZonesModule;
+}
+/**
+ * The zone provisioning gives a store for its country when it is sent no zones
+ * (`platform.provisionStore`, see `ProvisionStoreInput.defaultTaxZoneId`): the most SPECIFIC
+ * zone that contains the country — the fewest members — so a dedicated `Benelux` wins over a
+ * catch-all `Europe`. Ties break on name, then id, so the answer never depends on list order.
+ * Country codes compare case-insensitively.
+ *
+ * Null when no zone contains the country (or the code is blank): provisioning then refuses to
+ * guess, and so does this.
+ *
+ * Pass the COMPLETE zone list with members (`geo.zones.list({ members: true })`, walked): a cut
+ * list can answer a less specific zone than the server would.
+ *
+ * The server re-judges this: provisioning sent no zones resolves them itself with the same rule.
+ * A form that pre-fills with it and finds both zones unchanged at submit can leave them out and
+ * let the server have the last word.
+ */
+export declare function mostSpecificZone<T extends {
+    id: string;
+    name: string;
+    members: {
+        code: string;
+    }[];
+}>(zones: readonly T[], countryCode: string | null | undefined): T | null;
+export declare const COUNTRY_FIELDS = "\n  id\n  name\n  code\n  enabled\n  createdAt\n  updatedAt\n";
+export declare const ZONE_FIELDS = "\n  id\n  name\n  createdAt\n  updatedAt\n";
+export declare const ZONE_MEMBER_FIELDS = "\n  members {\n    id\n    name\n    code\n    enabled\n    type\n  }\n";
+export declare const GEO_COUNTRIES_QUERY = "\n  query GeoCountries($options: CountryListOptions) {\n    countries(options: $options) {\n      items { \n  id\n  name\n  code\n  enabled\n  createdAt\n  updatedAt\n }\n      totalItems\n    }\n  }\n";
+export declare const GEO_ZONES_QUERY = "\n  query GeoZones($options: ZoneListOptions) {\n    zones(options: $options) {\n      items { \n  id\n  name\n  createdAt\n  updatedAt\n }\n      totalItems\n    }\n  }\n";
+export declare const GEO_ZONES_WITH_MEMBERS_QUERY = "\n  query GeoZonesWithMembers($options: ZoneListOptions) {\n    zones(options: $options) {\n      items { \n  id\n  name\n  createdAt\n  updatedAt\n \n  members {\n    id\n    name\n    code\n    enabled\n    type\n  }\n }\n      totalItems\n    }\n  }\n";
+export declare const GEO_ZONE_QUERY = "\n  query GeoZone($id: ID!) {\n    zone(id: $id) { \n  id\n  name\n  createdAt\n  updatedAt\n \n  members {\n    id\n    name\n    code\n    enabled\n    type\n  }\n }\n  }\n";
+export declare function createGeoModule(transport: Transport): GeoModule;

package/dist/geo/index.js

@@ -0,0 +1,107 @@
+import { fieldOf, vendureListPage } from '../catalog/types.js';
+/**
+ * The zone provisioning gives a store for its country when it is sent no zones
+ * (`platform.provisionStore`, see `ProvisionStoreInput.defaultTaxZoneId`): the most SPECIFIC
+ * zone that contains the country — the fewest members — so a dedicated `Benelux` wins over a
+ * catch-all `Europe`. Ties break on name, then id, so the answer never depends on list order.
+ * Country codes compare case-insensitively.
+ *
+ * Null when no zone contains the country (or the code is blank): provisioning then refuses to
+ * guess, and so does this.
+ *
+ * Pass the COMPLETE zone list with members (`geo.zones.list({ members: true })`, walked): a cut
+ * list can answer a less specific zone than the server would.
+ *
+ * The server re-judges this: provisioning sent no zones resolves them itself with the same rule.
+ * A form that pre-fills with it and finds both zones unchanged at submit can leave them out and
+ * let the server have the last word.
+ */
+export function mostSpecificZone(zones, countryCode) {
+    const code = typeof countryCode === 'string' ? countryCode.trim().toUpperCase() : '';
+    if (code === '')
+        return null;
+    const candidates = zones.filter((zone) => zone.members.some((member) => member.code?.toUpperCase() === code));
+    const [best] = [...candidates].sort((a, b) => {
+        const size = a.members.length - b.members.length;
+        if (size !== 0)
+            return size;
+        const name = a.name.localeCompare(b.name, 'en');
+        if (name !== 0)
+            return name;
+        return a.id.localeCompare(b.id);
+    });
+    return best ?? null;
+}
+export const COUNTRY_FIELDS = /* GraphQL */ `
+  id
+  name
+  code
+  enabled
+  createdAt
+  updatedAt
+`;
+export const ZONE_FIELDS = /* GraphQL */ `
+  id
+  name
+  createdAt
+  updatedAt
+`;
+export const ZONE_MEMBER_FIELDS = /* GraphQL */ `
+  members {
+    id
+    name
+    code
+    enabled
+    type
+  }
+`;
+export const GEO_COUNTRIES_QUERY = /* GraphQL */ `
+  query GeoCountries($options: CountryListOptions) {
+    countries(options: $options) {
+      items { ${COUNTRY_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const GEO_ZONES_QUERY = /* GraphQL */ `
+  query GeoZones($options: ZoneListOptions) {
+    zones(options: $options) {
+      items { ${ZONE_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const GEO_ZONES_WITH_MEMBERS_QUERY = /* GraphQL */ `
+  query GeoZonesWithMembers($options: ZoneListOptions) {
+    zones(options: $options) {
+      items { ${ZONE_FIELDS} ${ZONE_MEMBER_FIELDS} }
+      totalItems
+    }
+  }
+`;
+export const GEO_ZONE_QUERY = /* GraphQL */ `
+  query GeoZone($id: ID!) {
+    zone(id: $id) { ${ZONE_FIELDS} ${ZONE_MEMBER_FIELDS} }
+  }
+`;
+/**
+ * Vendure's list queries add no ORDER BY of their own, and `skip/take` over an unordered query
+ * can repeat or skip rows between two requests. Every list here is ordered by id, the one unique
+ * key a sort can name (a GraphQL sort input applies its fields in the SCHEMA's order, where `id`
+ * comes first, so `{ name, id }` is id order too), so a walk answers each row exactly once.
+ */
+const BY_ID = { id: 'ASC' };
+export function createGeoModule(transport) {
+    function listZones(options) {
+        return vendureListPage(transport, options?.members === true ? GEO_ZONES_WITH_MEMBERS_QUERY : GEO_ZONES_QUERY, 'zones', (skip, take) => ({ options: { skip, take, sort: BY_ID } }), options);
+    }
+    return {
+        countries: {
+            list: (options) => vendureListPage(transport, GEO_COUNTRIES_QUERY, 'countries', (skip, take) => ({ options: { skip, take, sort: BY_ID } }), options),
+        },
+        zones: {
+            list: listZones,
+            get: (id, options) => fieldOf(transport, GEO_ZONE_QUERY, 'zone', { id }, options),
+        },
+    };
+}