@porulle/plugin-channel-connector 0.73.3 → 0.74.0

package/dist/service.d.ts

@@ -1,9 +1,10 @@
 import { z } from "zod";
-import type { Actor, ChannelCancelOrderInput, ChannelCatalogItem, ChannelConnector, ChannelOrderSlice, ChannelPushCatalogField, ChannelPushCatalogImage, ChannelPushCatalogItem, ChannelPushCatalogItemOutcome, ChannelPushCatalogResult, ChannelStore, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
+import type { Actor, ChannelCancelOrderInput, ChannelCatalogItem, ChannelConnector, ChannelWebhookEvent, ChannelOrderSlice, ChannelPushCatalogField, ChannelPushCatalogImage, ChannelPushCatalogItem, ChannelPushCatalogItemOutcome, ChannelPushCatalogResult, ChannelStore, PluginDb, PluginResult, PluginTxFn } from "@porulle/core";
 import type { ChannelCatalogImage } from "@porulle/core";
 import type { FieldOwner, FieldPath } from "@porulle/core";
 import type { JobsAdapter } from "@porulle/core";
 import { type ChannelCatalogPush, type ChannelCatalogConflict, type ChannelOrderExport, type ChannelRefundRequest, type ConnectedStore } from "./schema.js";
+import type { StoreHealth } from "./schema.js";
 import { type CatalogFieldMapping, type CatalogFieldTarget } from "./catalog-field-mapping.js";
 export type ExportState = ChannelOrderExport["state"];
 export type CatalogPushState = ChannelCatalogPush["state"];
@@ -26,6 +27,10 @@ export declare const CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION = 20;
  * The reason a platform order is cancelled under when its STORE cancelled it. The cancel hook skips
  * cancelling at the store for exactly this reason, so the two directions cannot loop.
  */
+/** How stale a store order may be before a read point queues a refresh of it. */
+export declare const REMOTE_ORDER_REFRESH_MS: number;
+/** How often a merchant's visit may make the plugin call a store to check its health. */
+export declare const STORE_HEALTH_INTERVAL_MS: number;
 export declare const CHANNEL_ORDER_CANCELLED_REASON = "channel_order_cancelled";
 export declare function catalogPushRetryDelayMs(attempts: number): number;
 export interface CatalogPushJobResult extends Record<string, unknown> {
@@ -374,6 +379,10 @@ export interface CatalogPageConvergence extends Record<string, unknown> {
     heroesImported: number;
     mediaFailures: CatalogMediaFailure[];
     deferredMedia: CatalogDeferredMedia[];
+    /** Fields the store's value did not overwrite because the platform owns them. */
+    skipped: CatalogFieldSkip[];
+    /** Shared fields both sides changed, held for an operator. */
+    conflicts: CatalogFieldConflict[];
     warnings: string[];
 }
 export interface ImportImageSelection {
@@ -493,6 +502,8 @@ export declare class ChannelConnectorService {
     /** The slug an existing product converges to: its current one while that is still in the family
      *  of the handle the store sends, so a slug is never recomputed out from under a shared link. */
     private slugToKeep;
+    /** This organization's store of `provider` at `storeDomain`, whatever its status. */
+    storeByDomain(orgId: string, provider: string, storeDomain: string): Promise<PublicConnectedStore | undefined>;
     getStoresByDomain(shopDomain: string): Promise<ConnectedStore[]>;
     resolveCatalogFieldMapping(store: Pick<ConnectedStore, "provider" | "catalogFieldMapping">, filterableCustomFields?: ReadonlySet<string> | Readonly<Record<string, boolean>>, warnings?: string[]): CatalogFieldMapping;
     buildCatalogPushItems(orgId: string, storeId: string, entityIds: string[], options?: BuildCatalogPushItemsOptions): Promise<PluginResult<BuildCatalogPushItemsResult>>;
@@ -511,12 +522,37 @@ export declare class ChannelConnectorService {
      * provider that subscribes per store is registered after commit, at an absolute address; the
      * consumer's follow-on work ({@link AfterStoreConnected}) runs after that.
      */
+    /**
+     * Connects a store and runs its follow-on work (subscribe, first import) before answering. For a
+     * provider whose callback must be answered at once, see {@link saveConnectingStore} and
+     * {@link completeConnect}, which this is the two halves of.
+     */
     connectStore(orgId: string, input: {
         provider: string;
         credentials: Record<string, unknown>;
         storeDomain: string;
         webhookSecret?: string;
     }, actor: StoreConnectActor): Promise<PluginResult<PublicConnectedStore>>;
+    /**
+     * Writes the store with its credentials in status `connecting`, bound to the actor's vendor, and
+     * nothing else: no call to the store. Reconnecting a store this organization already has refreshes
+     * its row instead of adding one.
+     */
+    saveConnectingStore(orgId: string, input: {
+        provider: string;
+        credentials: Record<string, unknown>;
+        storeDomain: string;
+        webhookSecret?: string;
+    }, actor: StoreConnectActor): Promise<PluginResult<PublicConnectedStore>>;
+    /**
+     * The work after the credentials are saved: subscribe the store to its connector's topics (all or
+     * none — a partial subscription is removed), mark it `connected`, then the host's follow-on work.
+     * A failure leaves the store in `error` with the reason the merchant will read, unless the host
+     * already moved it (it disconnects a store it refuses).
+     */
+    completeConnect(orgId: string, storeId: string, actor: StoreConnectActor): Promise<PluginResult<PublicConnectedStore>>;
+    /** Where a store that subscribes per store delivers its webhooks: absolute, on this deployment's public origin. */
+    webhookCallbackUrl(storeId: string): string;
     /** The store with credentials good for a call the host makes itself, e.g. its own Admin API write. */
     liveStore(orgId: string, storeId: string): Promise<PluginResult<ChannelStore>>;
     /** The consumer's claims for a connection starting from this request. See {@link ConnectClaims}. */
@@ -529,6 +565,17 @@ export declare class ChannelConnectorService {
     reachableStore(orgId: string, id: string, context: StoreReadContext | undefined): Promise<PluginResult<ConnectedStore>>;
     disconnectStore(orgId: string, id: string, context?: StoreReadContext): Promise<PluginResult<PublicConnectedStore>>;
     disconnectStoreSystem(orgId: string, id: string, redactDomain?: boolean): Promise<PluginResult<PublicConnectedStore>>;
+    /**
+     * Checks the store's webhook subscriptions and key and repairs what it can, when a merchant looks:
+     * there is no scheduled check. At most once per {@link STORE_HEALTH_INTERVAL_MS} per store; inside
+     * that window the last result is answered without calling the store.
+     */
+    checkStoreHealth(orgId: string, id: string, context?: StoreReadContext): Promise<PluginResult<StoreHealth & {
+        status: ConnectedStore["status"];
+        statusReason: string | null;
+        lastEventAt: Date | null;
+        cached: boolean;
+    }>>;
     getStore(orgId: string, id: string, context?: StoreReadContext): Promise<PluginResult<PublicConnectedStore>>;
     listStores(orgId: string, context?: StoreReadContext): Promise<PluginResult<PublicConnectedStore[]>>;
     validateLineStock(orgId: string, lines: ChannelStockLine[], timeoutMs?: number): Promise<void>;
@@ -624,28 +671,38 @@ export declare class ChannelConnectorService {
      * the whole inventory and every map row on every 20-level step.
      */
     private syncInventoryPage;
-    handleWebhook(orgId: string, storeId: string, event: {
-        id: string;
-        type: string;
-        data: unknown;
-    }): Promise<PluginResult<{
-        processed: true;
+    /**
+     * One verified store delivery. The store's connector says what it means ({@link ChannelEvent}); this
+     * acts on the meaning and never on a topic or payload field. A delivery the connector does not act
+     * on is logged as unmapped and answered `processed: false`, never reported as applied.
+     */
+    handleWebhook(orgId: string, storeId: string, delivery: ChannelWebhookEvent): Promise<PluginResult<{
+        processed: boolean;
         data?: ChannelComplianceData;
         redacted?: number;
     }>>;
+    private applyChannelEvent;
     private complianceEmail;
     private channelCustomerExports;
     private channelCustomerDataRequest;
     private redactCustomerData;
     private redactShopData;
-    private resolveOrderId;
+    /**
+     * For a read point (a shopper opening their order): each of the order's store orders not read for
+     * {@link REMOTE_ORDER_REFRESH_MS} is queued for one refresh, so a store-side cancel, shipment or
+     * refund whose delivery never arrived still reaches the platform. No schedule: someone looked.
+     * Answers how many were queued.
+     */
+    refreshStaleRemoteOrders(orgId: string, orderId: string, jobs: JobsAdapter): Promise<number>;
+    /** The store's current state of one order we pushed, applied as if its delivery had arrived. */
+    refreshRemoteOrder(orgId: string, storeId: string, remoteOrderId: string): Promise<PluginResult<{
+        events: number;
+    }>>;
+    private orderForRemote;
     /** Archives this store's product mapped to `externalId`, unless the platform owns its status. */
     private archiveMappedProduct;
     private setMappedInventory;
     private setInventoryLevel;
-    /** This store's mapped variant whose import recorded `metadata.inventoryItemId`; null when none, or when two claim it. */
-    private variantForInventoryItem;
-    private convergeCatalogItem;
     private createRefundRequest;
     private executeRefund;
     listRefundRequests(orgId: string): Promise<PluginResult<ChannelRefundRequest[]>>;
@@ -665,10 +722,10 @@ export declare class ChannelConnectorService {
      */
     cancelRemoteOrders(orgId: string, orderId: string, input: ChannelCancelOrderInput): Promise<PluginResult<number>>;
     /**
-     * One core fulfilment record per store fulfilment the order body carries, keyed on the store's
-     * fulfilment id (`metadata.channelFulfillmentId`) so a replay records nothing twice. Each records
-     * the lines it shipped, matched by the store's variant id; one whose lines cannot be matched
-     * records every line not yet fulfilled. A fulfilment the store cancelled is not a parcel.
+     * One core fulfilment record per store parcel, keyed on the store's parcel id
+     * (`metadata.channelFulfillmentId`) so a replay records nothing twice. Each records the lines it
+     * shipped, matched by the store's variant id; one whose lines cannot be matched (or that names
+     * none) records every line not yet fulfilled.
      */
     private recordChannelFulfillments;
     /** Every line with quantity still to ship, for a parcel whose own lines could not be matched. */