@porulle/plugin-channel-connector 0.73.3 → 0.74.1

package/dist/index.d.ts

@@ -27,5 +27,5 @@ export declare const CHANNEL_MAX_BATCHES_PER_SWEEP = 5000;
 export { signState, verifyState } from "./oauth-state.js";
 export type { BackfillCatalogOptions, BackfillCatalogReport, BuildCatalogPushItemsOptions, BuildCatalogPushItemsResult, CatalogPushAssemblyField, CatalogPushAssemblyImage, CatalogPushAssemblyItem, CatalogPushPreviewBefore, CatalogPushPreviewBeforeStatus, CatalogPushPreviewDiff, CatalogPushPreviewItem, CatalogPushPreviewResult, CatalogPushPreviewUnavailable, PushCatalogToStoreResult, CatalogPushJobResult, CatalogConvergenceFailure, CatalogFieldConflict, CatalogFieldSkip, CatalogPushFieldSkip, CatalogPushSkipReason, CatalogConflictState, CatalogWriteSettings, AfterStoreConnected, BindConnectedStore, ChannelComplianceData, ChannelConnectorPluginOptions, ConfineStores, ConnectClaims, OnStoreCatalogChanged, StoreConnectActor, StoreReadContext, ChannelStockLine, ExportState, PublicConnectedStore, ReconcileReport, } from "./service.js";
 export type { OAuthStatePayload, OAuthStateResult } from "./oauth-state.js";
-export type { ChannelCatalogPush, ChannelCatalogPushEvent, ChannelCatalogConflict, ChannelCatalogConflictEvent, ChannelEntityMapEntry, ChannelExportEvent, ChannelOrderExport, ChannelRefundEvent, ChannelRefundRequest, ConnectedStore, } from "./schema.js";
+export type { ChannelCatalogPush, ChannelCatalogPushEvent, ChannelCatalogConflict, ChannelCatalogConflictEvent, ChannelEntityMapEntry, ChannelExportEvent, ChannelOrderExport, ChannelRefundEvent, ChannelRefundRequest, ConnectedStore, StoreHealth, } from "./schema.js";
 export declare function channelConnectorPlugin(options?: ChannelConnectorPluginOptions): import("@porulle/core").CommercePlugin;

package/dist/index.js

@@ -143,6 +143,12 @@ function callbackUri(raw, redirect, provider) {
     }
     return new URL(`/api/channels/oauth/${provider}/callback`, origin).toString();
 }
+const refreshOrderInput = z.object({ orgId: z.string(), storeId: z.string(), remoteOrderId: z.string() });
+const completeConnectInput = z.object({
+    orgId: z.string(),
+    storeId: z.string(),
+    actor: z.object({ orgId: z.string(), userId: z.string(), claims: z.record(z.string(), z.string()) }),
+});
 export function channelConnectorPlugin(options = {}) {
     const jobs = [
         {
@@ -300,7 +306,34 @@ export function channelConnectorPlugin(options = {}) {
                 });
                 if (!result.ok)
                     throw new Error(result.error);
-                return { output: { processed: true } };
+                return { output: { processed: result.value.processed } };
+            },
+        },
+        {
+            // A read point found a store order not read for a while; its current state is applied as if
+            // the delivery for it had arrived. Serialized with that store's deliveries.
+            slug: "channel/refresh-order",
+            concurrency: { key: (input) => `webhook:${String(input.storeId)}` },
+            handler: async ({ input, ctx }) => {
+                const parsed = refreshOrderInput.parse(input);
+                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+                const result = await service.refreshRemoteOrder(parsed.orgId, parsed.storeId, parsed.remoteOrderId);
+                if (!result.ok)
+                    throw new Error(result.error);
+                return { output: result.value };
+            },
+        },
+        {
+            // The second half of a connect whose callback had to be answered at once (WooCommerce's): subscribe
+            // the store and start its first import. Not retried: a failure leaves the store in `error` with
+            // the reason the merchant reads, and reconnecting is the retry.
+            slug: "channel/complete-connect",
+            concurrency: { key: (input) => `connect:${String(input.storeId)}` },
+            handler: async ({ input, ctx }) => {
+                const parsed = completeConnectInput.parse(input);
+                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+                const result = await service.completeConnect(parsed.orgId, parsed.storeId, parsed.actor);
+                return { output: result.ok ? { status: result.value.status } : { error: result.code ?? "COMPLETE_CONNECT_FAILED", message: result.error } };
             },
         },
         {
@@ -366,7 +399,18 @@ export function channelConnectorPlugin(options = {}) {
                 if (!userId)
                     return oauthError(403, "USER_REQUIRED", "Connecting a store needs a signed-in user.");
                 const typed = String(query.shop ?? query.store ?? "");
-                const storeDomain = connector.normalizeStoreDomain ? connector.normalizeStoreDomain(typed) : typed;
+                // A connector that can look at the store first does, so the merchant is told what is wrong
+                // here rather than landing on a broken page at their own site.
+                let storeDomain;
+                if (connector.probeStore) {
+                    const probed = await connector.probeStore(typed);
+                    if (!probed.ok)
+                        return connectOutcome(oauth.postConnectRedirect, { error: probed.error.code, message: probed.error.message });
+                    storeDomain = probed.value.storeDomain;
+                }
+                else {
+                    storeDomain = connector.normalizeStoreDomain ? connector.normalizeStoreDomain(typed) : typed;
+                }
                 if (!storeDomain)
                     return connectOutcome(oauth.postConnectRedirect, { error: "INVALID_STORE_DOMAIN", message: `"${typed}" does not name a ${provider} store.` });
                 // Refused HERE, before the merchant reaches the provider: a grant issued for a shop retires
@@ -395,6 +439,11 @@ export function channelConnectorPlugin(options = {}) {
                     return connectOutcome(oauth.postConnectRedirect, { error: authUrl.error.code, message: authUrl.error.message });
                 return oauthRedirect(authUrl.value);
             });
+            // Two shapes of callback reach here. Shopify's is the merchant's BROWSER (GET): the connection
+            // completes in the request and the browser lands on the outcome. WooCommerce's is the STORE
+            // posting the keys (POST), and it deletes them on anything but a 200 or after 60 seconds, so
+            // the keys are saved, the answer is immediate, and the rest runs as `channel/complete-connect`.
+            // Its browser then returns separately (GET with `return=1`) and lands on the store's real state.
             const handleOAuthCallback = async ({ params, raw }) => {
                 const oauth = options.oauth;
                 if (!oauth?.stateSecret || !oauth.postConnectRedirect)
@@ -407,36 +456,54 @@ export function channelConnectorPlugin(options = {}) {
                     return oauthError(501, "OAUTH_UNSUPPORTED", `Connector "${provider}" does not support OAuth onboarding.`);
                 const request = raw.req.raw;
                 const requestUrl = new URL(request.url);
+                const posted = request.method === "POST";
                 const state = requestUrl.searchParams.get("state");
-                const refused = (error, message) => connectOutcome(oauth.postConnectRedirect, { error, message });
+                // A store posting keys is answered with a status it understands; a browser is sent to the outcome.
+                const refused = (error, message, status = 400) => posted
+                    ? oauthError(status, error, message)
+                    : connectOutcome(oauth.postConnectRedirect, { error, message });
                 if (!state)
                     return refused("INVALID_OAUTH_STATE", "The connection was not started here, or its link was altered.");
-                const landing = provider === "woocommerce" && request.method === "GET" && requestUrl.searchParams.get("return") === "1";
                 const verified = verifyState(state, oauth.stateSecret, Math.floor(Date.now() / 1000));
                 if (!verified.ok || verified.value.provider !== provider)
                     return refused("INVALID_OAUTH_STATE", "The connection link expired; start again.");
-                if (landing)
-                    return oauthRedirect(oauth.postConnectRedirect);
+                if (!posted && requestUrl.searchParams.get("return") === "1") {
+                    if (requestUrl.searchParams.get("success") === "0")
+                        return refused("CONNECT_DECLINED", "You declined the connection in your store, so nothing was connected.");
+                    const landed = await service.storeByDomain(verified.value.orgId, provider, verified.value.shopDomain);
+                    if (!landed)
+                        return refused("CONNECT_NOT_RECEIVED", "Your store did not send its keys. Approve the connection again.");
+                    return connectOutcome(oauth.postConnectRedirect, { connected: landed.id });
+                }
                 const [consumed] = await db.insert(processedWebhookEvents).values({
                     eventId: oauthStateEventId(verified.value.jti),
                     provider: `oauth:${provider}`,
                     eventType: "oauth_state",
                 }).onConflictDoNothing().returning({ id: processedWebhookEvents.id });
                 if (!consumed)
-                    return refused("OAUTH_STATE_REPLAYED", "This connection link was already used; start again.");
-                const completed = await connector.completeAuth(request, { storeDomain: verified.value.shopDomain });
+                    return refused("OAUTH_STATE_REPLAYED", "This connection link was already used; start again.", 409);
+                const completed = await connector.completeAuth(request, { storeDomain: verified.value.shopDomain, state });
                 if (!completed.ok)
                     return refused(completed.error.code, completed.error.message);
                 if (completed.value.storeDomain !== verified.value.shopDomain)
                     return refused("OAUTH_STORE_MISMATCH", "The store that answered is not the one the connection was started for.");
-                const connected = await service.connectStore(verified.value.orgId, {
-                    provider,
-                    storeDomain: verified.value.shopDomain,
-                    credentials: completed.value.credentials,
-                }, { orgId: verified.value.orgId, userId: verified.value.userId, claims: verified.value.claims });
-                if (!connected.ok)
-                    return refused(connected.code ?? "STORE_CONNECTION_FAILED", connected.error);
-                return connectOutcome(oauth.postConnectRedirect, { connected: connected.value.id });
+                const actor = { orgId: verified.value.orgId, userId: verified.value.userId, claims: verified.value.claims };
+                const input = { provider, storeDomain: verified.value.shopDomain, credentials: completed.value.credentials };
+                if (!posted) {
+                    const connected = await service.connectStore(verified.value.orgId, input, actor);
+                    if (!connected.ok)
+                        return refused(connected.code ?? "STORE_CONNECTION_FAILED", connected.error);
+                    return connectOutcome(oauth.postConnectRedirect, { connected: connected.value.id });
+                }
+                const saved = await service.saveConnectingStore(verified.value.orgId, input, actor);
+                if (!saved.ok)
+                    return refused(saved.code ?? "STORE_CONNECTION_FAILED", saved.error, 409);
+                await ctx.services.jobs.enqueue("channel/complete-connect", { orgId: verified.value.orgId, storeId: saved.value.id, actor }, {
+                    organizationId: verified.value.orgId,
+                    concurrencyKey: `connect:${saved.value.id}`,
+                    supersedes: false,
+                });
+                return new Response(JSON.stringify({ data: { received: true } }), { status: 200, headers: { "content-type": "application/json" } });
             };
             channels.get("/oauth/{provider}/callback")
                 .summary("Complete channel OAuth onboarding")
@@ -446,31 +513,44 @@ export function channelConnectorPlugin(options = {}) {
                 .summary("Receive channel OAuth credentials")
                 .params(z.object({ provider: z.string().min(1) }))
                 .handler(handleOAuthCallback);
+            // Every delivery for a provider that signs per STORE (WooCommerce) arrives here. The answer is
+            // 200 for anything verified, before any work: WooCommerce never retries a delivery, counts every
+            // non-2xx (and every redirect) as a failure, and silently disables a subscription after repeated
+            // failures. The work runs as a job, which retries through the queue, never through the store.
             channels.post("/webhooks/{storeId}")
                 .summary("Receive a channel webhook")
+                .params(z.object({ storeId: z.string().uuid() }))
                 .handler(async ({ params, raw }) => {
                 const context = raw;
-                const storeId = params.storeId;
-                const [store] = await db.select().from(connectedStores).where(eq(connectedStores.id, storeId));
+                const [store] = await db.select().from(connectedStores).where(eq(connectedStores.id, params.storeId));
                 if (!store || !store.webhookSecret)
-                    return context.json({ error: { code: "UNAUTHORIZED", message: "Webhook store is not available." } }, 401);
+                    return context.json({ error: { code: "NOT_FOUND", message: "No store receives webhooks here." } }, 404);
                 const connector = service.getConnector(store.provider);
                 if (!connector?.verifyWebhook)
-                    return context.json({ error: { code: "UNAUTHORIZED", message: "Webhook provider is not configured for per-store deliveries." } }, 401);
+                    return context.json({ error: { code: "NOT_FOUND", message: "This store's provider does not deliver per-store webhooks." } }, 404);
                 const verified = await connector.verifyWebhook(store, context.req.raw);
                 if (!verified.ok)
                     return context.json({ error: { code: "UNAUTHORIZED", message: "Invalid webhook signature." } }, 401);
-                const [inserted] = await db.insert(processedWebhookEvents).values({ eventId: verified.value.id, provider: store.provider, eventType: verified.value.type }).onConflictDoNothing().returning({ id: processedWebhookEvents.id });
-                if (!inserted)
+                // The unsigned ping a provider sends when a subscription is created carries nothing to do.
+                if (verified.value === null)
+                    return context.json({ data: { received: true } });
+                const delivery = verified.value;
+                // The connector's key is unique within one store; the store id makes it unique here.
+                const [marked] = await db.insert(processedWebhookEvents).values({ eventId: `${store.id}:${delivery.id}`, provider: store.provider, eventType: delivery.type }).onConflictDoNothing().returning({ id: processedWebhookEvents.id });
+                if (!marked)
                     return context.json({ data: { received: true, duplicate: true } });
-                const handled = await service.handleWebhook(store.organizationId, store.id, verified.value);
-                if (!handled.ok)
-                    return context.json({ error: { code: "WEBHOOK_PROCESSING_FAILED", message: handled.error } }, 422);
-                return context.json({ data: {
-                        received: true,
-                        ...(handled.value.data ? { data: handled.value.data } : {}),
-                        ...(handled.value.redacted !== undefined ? { redacted: handled.value.redacted } : {}),
-                    } });
+                try {
+                    await ctx.services.jobs.enqueue("channel/apply-webhook", { orgId: store.organizationId, storeId: store.id, id: delivery.id, topic: delivery.type, data: delivery.data }, {
+                        organizationId: store.organizationId,
+                        concurrencyKey: `webhook:${store.id}`,
+                        supersedes: false,
+                    });
+                }
+                catch (error) {
+                    await db.delete(processedWebhookEvents).where(eq(processedWebhookEvents.id, marked.id));
+                    return context.json({ error: { code: "WEBHOOK_NOT_ACCEPTED", message: error instanceof Error ? error.message : "The delivery could not be queued." } }, 503);
+                }
+                return context.json({ data: { received: true } });
             });
             // Every delivery for a provider that signs per APP — Shopify's catalogue, stock, order, uninstall
             // and mandatory compliance topics alike — arrives here, at the one address its app configuration
@@ -628,6 +708,10 @@ export function channelConnectorPlugin(options = {}) {
                 const values = input;
                 return unwrap(await service.previewCatalogPush(orgId, params.storeId, values.entityIds));
             });
+            channels.post("/stores/{id}/health")
+                .summary("Check a store's webhooks and key, repairing what can be repaired")
+                .permission("channels:connect")
+                .handler(async ({ params, orgId, actor, raw }) => unwrap(await service.checkStoreHealth(orgId, params.id, { orgId, actor, raw })));
             channels.post("/stores/{id}/disconnect")
                 .summary("Disconnect a channel store")
                 .permission("channels:connect")

package/dist/live-credentials.d.ts

@@ -18,12 +18,15 @@ import type { ChannelConnector, ChannelConnectorError, ChannelStore, PluginDb, R
 export declare function resolveLiveCredentials(connector: ChannelConnector, db: PluginDb, store: ChannelStore, options?: {
     force?: boolean;
 }): Promise<Result<ChannelStore, ChannelConnectorError>>;
+/** Why a store whose key the provider refused is in `error`. */
+export declare const CREDENTIALS_REJECTED_REASON = "The store no longer accepts the key it gave us (it was revoked, or the user who approved it was removed). Reconnect the store.";
 /**
  * The connector with every store-taking method routed through {@link resolveLiveCredentials}, so no
- * call site can start on a lapsed token by forgetting to ask. Returned unchanged when the connector's
- * credentials never expire.
+ * call site can start on a lapsed token by forgetting to ask.
  *
  * A call the provider answers with {@link CHANNEL_CREDENTIALS_REJECTED} — a token retired before its
- * stated expiry — is retried ONCE on credentials refreshed by force. A second rejection is the answer.
+ * stated expiry — is retried ONCE on credentials refreshed by force, for a connector that can refresh.
+ * A rejection that cannot be refreshed away (a second one, or a connector whose keys never expire,
+ * such as WooCommerce's) marks the store `error` so it reads as "reconnect".
  */
 export declare function withLiveCredentials(connector: ChannelConnector, db: PluginDb): ChannelConnector;

package/dist/live-credentials.js

@@ -40,17 +40,21 @@ export async function resolveLiveCredentials(connector, db, store, options = {})
         return Err({ code: "STORE_NOT_FOUND", message: `Connected store ${store.id} no longer exists.`, retriable: false });
     return Ok({ ...store, credentials: current.credentials });
 }
+/** Why a store whose key the provider refused is in `error`. */
+export const CREDENTIALS_REJECTED_REASON = "The store no longer accepts the key it gave us (it was revoked, or the user who approved it was removed). Reconnect the store.";
+async function markCredentialsRejected(db, storeId) {
+    await db.update(connectedStores).set({ status: "error", statusReason: CREDENTIALS_REJECTED_REASON, updatedAt: new Date() }).where(eq(connectedStores.id, storeId));
+}
 /**
  * The connector with every store-taking method routed through {@link resolveLiveCredentials}, so no
- * call site can start on a lapsed token by forgetting to ask. Returned unchanged when the connector's
- * credentials never expire.
+ * call site can start on a lapsed token by forgetting to ask.
  *
  * A call the provider answers with {@link CHANNEL_CREDENTIALS_REJECTED} — a token retired before its
- * stated expiry — is retried ONCE on credentials refreshed by force. A second rejection is the answer.
+ * stated expiry — is retried ONCE on credentials refreshed by force, for a connector that can refresh.
+ * A rejection that cannot be refreshed away (a second one, or a connector whose keys never expire,
+ * such as WooCommerce's) marks the store `error` so it reads as "reconnect".
  */
 export function withLiveCredentials(connector, db) {
-    if (!connector.liveCredentials)
-        return connector;
     const around = (call) => async (store, ...args) => {
         const current = await resolveLiveCredentials(connector, db, store);
         if (!current.ok)
@@ -58,10 +62,17 @@ export function withLiveCredentials(connector, db) {
         const first = await call.call(connector, current.value, ...args);
         if (first.ok || first.error.code !== CHANNEL_CREDENTIALS_REJECTED)
             return first;
+        if (!connector.liveCredentials) {
+            await markCredentialsRejected(db, store.id);
+            return first;
+        }
         const refreshed = await resolveLiveCredentials(connector, db, current.value, { force: true });
         if (!refreshed.ok)
             return refreshed;
-        return call.call(connector, refreshed.value, ...args);
+        const second = await call.call(connector, refreshed.value, ...args);
+        if (!second.ok && second.error.code === CHANNEL_CREDENTIALS_REJECTED)
+            await markCredentialsRejected(db, store.id);
+        return second;
     };
     return {
         ...connector,
@@ -76,6 +87,11 @@ export function withLiveCredentials(connector, db) {
         ...(connector.pushCatalog ? { pushCatalog: around(connector.pushCatalog) } : {}),
         ...(connector.reserve ? { reserve: around(connector.reserve) } : {}),
         ...(connector.registerWebhooks ? { registerWebhooks: around(connector.registerWebhooks) } : {}),
+        ...(connector.unregisterWebhooks ? { unregisterWebhooks: around(connector.unregisterWebhooks) } : {}),
+        ...(connector.webhookHealth ? { webhookHealth: around(connector.webhookHealth) } : {}),
+        ...(connector.decodeWebhook ? { decodeWebhook: around(connector.decodeWebhook) } : {}),
+        ...(connector.orderEvents ? { orderEvents: around(connector.orderEvents) } : {}),
         ...(connector.cancelOrder ? { cancelOrder: around(connector.cancelOrder) } : {}),
+        ...(connector.requestReturn ? { requestReturn: around(connector.requestReturn) } : {}),
     };
 }

package/dist/mock-connector.d.ts

@@ -24,6 +24,68 @@ export declare function mockChannelConnector(options?: MockChannelConnectorOptio
         items: ChannelCatalogItem[];
         nextCursor: null;
     }, never>>;
+    /** The catalogue as it stands when asked: a test changes `options.catalog` to change "the store". */
+    fetchCatalogItems(_store: ChannelStore, externalIds: string[]): Promise<import("@porulle/core").Result<ChannelCatalogItem[], never>>;
+    decodeWebhook(_store: ChannelStore, event: import("@porulle/core").ChannelWebhookEvent): Promise<{
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+            retriable: false;
+        };
+    } | {
+        ok: true;
+        value: ({
+            kind: "product.changed";
+            externalIds: string[];
+        } | {
+            kind: "product.deleted";
+            externalIds: string[];
+        } | {
+            kind: "inventory.changed";
+            levels: {
+                externalId: string;
+                available: number;
+            }[];
+        } | {
+            kind: "order.cancelled";
+            remoteOrderId: string;
+        } | {
+            kind: "order.fulfilled";
+            remoteOrderId: string;
+            partial: boolean;
+            shipments: {
+                remoteId: string;
+                lines: {
+                    externalVariantId: string;
+                    quantity: number;
+                }[];
+                carrier?: string;
+                trackingNumber?: string;
+                trackingUrl?: string;
+                source?: string;
+            }[];
+        } | {
+            kind: "refund.created";
+            remoteOrderId: string;
+            remoteRefundId: string;
+            lines: {
+                externalVariantId: string;
+                quantity: number;
+            }[];
+        } | {
+            kind: "return.updated";
+            remoteReturnId: string;
+            status: "cancelled" | "approved" | "declined" | "closed";
+        } | {
+            kind: "connection.revoked";
+        } | {
+            kind: "compliance.request";
+            request: "customer_data" | "customer_redact" | "shop_redact";
+            data: Record<string, unknown>;
+        })[];
+        meta?: Record<string, unknown>;
+    }>;
     fetchInventory(_store: ChannelStore, ids: string[] | undefined): Promise<{
         ok: false;
         error: CommerceValidationError;

package/dist/mock-connector.js

@@ -1,4 +1,5 @@
 import { CommerceValidationError, Err, Ok, defineChannelConnector, } from "@porulle/core";
+import { z } from "zod";
 const defaultCatalog = [{
         externalId: "mock-product-1",
         slug: "mock-channel-product",
@@ -48,6 +49,27 @@ const defaultCatalog = [{
                 prices: [{ currency: "USD", amount: 2500 }],
             }],
     }];
+const level = z.object({ externalId: z.string(), available: z.number() });
+const shipment = z.object({
+    remoteId: z.string(),
+    carrier: z.string().exactOptional(),
+    trackingNumber: z.string().exactOptional(),
+    trackingUrl: z.string().exactOptional(),
+    lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })),
+    source: z.string().exactOptional(),
+});
+/** A mock delivery's body IS what it means: one {@link ChannelEvent} or a list of them. */
+const channelEventSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("product.changed"), externalIds: z.array(z.string()) }),
+    z.object({ kind: z.literal("product.deleted"), externalIds: z.array(z.string()) }),
+    z.object({ kind: z.literal("inventory.changed"), levels: z.array(level) }),
+    z.object({ kind: z.literal("order.cancelled"), remoteOrderId: z.string() }),
+    z.object({ kind: z.literal("order.fulfilled"), remoteOrderId: z.string(), partial: z.boolean(), shipments: z.array(shipment) }),
+    z.object({ kind: z.literal("refund.created"), remoteOrderId: z.string(), remoteRefundId: z.string(), lines: z.array(z.object({ externalVariantId: z.string(), quantity: z.number().int() })) }),
+    z.object({ kind: z.literal("return.updated"), remoteReturnId: z.string(), status: z.enum(["approved", "declined", "closed", "cancelled"]) }),
+    z.object({ kind: z.literal("connection.revoked") }),
+    z.object({ kind: z.literal("compliance.request"), request: z.enum(["customer_data", "customer_redact", "shop_redact"]), data: z.record(z.string(), z.unknown()) }),
+]);
 export function mockChannelConnector(options = {}) {
     const orders = new Map();
     const catalog = new Map();
@@ -63,6 +85,17 @@ export function mockChannelConnector(options = {}) {
         async importCatalog(_store) {
             return Ok({ items: options.catalog ?? defaultCatalog, nextCursor: null });
         },
+        /** The catalogue as it stands when asked: a test changes `options.catalog` to change "the store". */
+        async fetchCatalogItems(_store, externalIds) {
+            const wanted = new Set(externalIds);
+            return Ok((options.catalog ?? defaultCatalog).filter((item) => wanted.has(item.externalId)));
+        },
+        async decodeWebhook(_store, event) {
+            const parsed = z.union([channelEventSchema, z.array(channelEventSchema)]).safeParse(event.data);
+            if (!parsed.success)
+                return Err({ code: "MOCK_WEBHOOK_MALFORMED", message: parsed.error.message, retriable: false });
+            return Ok(Array.isArray(parsed.data) ? parsed.data : [parsed.data]);
+        },
         async fetchInventory(_store, ids) {
             const requestedIds = ids ?? [];
             options.onFetchInventory?.(requestedIds);

package/dist/schema.d.ts

@@ -1,5 +1,15 @@
 import type { ChannelOrderAddress, ChannelPushCatalogItem } from "@porulle/core";
 import type { CatalogFieldMapping } from "./catalog-field-mapping.js";
+/** What the last on-visit check found. `webhooks`: subscriptions all active, recreated, or still failing. */
+export interface StoreHealth {
+    checkedAt: string;
+    webhooks: "ok" | "repaired" | "failing" | "not_applicable";
+    repaired: number;
+    missing: string[];
+    keyValid: boolean;
+    /** Why the check could not finish, when it could not. */
+    error?: string;
+}
 export declare const connectedStores: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
     name: "connected_stores";
     schema: undefined;
@@ -96,14 +106,67 @@ export declare const connectedStores: import("drizzle-orm/pg-core/table").PgTabl
             tableName: "connected_stores";
             dataType: "string";
             columnType: "PgText";
-            data: "error" | "connected" | "disconnected";
+            data: "error" | "connecting" | "connected" | "disconnected";
             driverParam: string;
             notNull: true;
             hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: ["connected", "disconnected", "error"];
+            enumValues: ["connecting", "connected", "disconnected", "error"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        statusReason: import("@porulle/core/drizzle").PgColumn<{
+            name: "status_reason";
+            tableName: "connected_stores";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        health: import("@porulle/core/drizzle").PgColumn<{
+            name: "health";
+            tableName: "connected_stores";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: StoreHealth;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: StoreHealth;
+        }>;
+        lastEventAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "last_event_at";
+            tableName: "connected_stores";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
             baseColumn: never;
             identity: undefined;
             generated: undefined;
@@ -1161,6 +1224,23 @@ export declare const channelOrderExports: import("drizzle-orm/pg-core/table").Pg
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        remoteCheckedAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "remote_checked_at";
+            tableName: "channel_order_exports";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         attempts: import("@porulle/core/drizzle").PgColumn<{
             name: "attempts";
             tableName: "channel_order_exports";

package/dist/schema.js

@@ -6,9 +6,15 @@ export const connectedStores = pgTable("connected_stores", {
     provider: text("provider").notNull(),
     credentials: jsonb("credentials").$type().notNull(),
     storeDomain: text("store_domain").notNull(),
-    status: text("status", { enum: ["connected", "disconnected", "error"] })
+    status: text("status", { enum: ["connecting", "connected", "disconnected", "error"] })
         .notNull()
         .default("connected"),
+    /** Why the store is in `error`, in words the merchant can act on. Null in every other status. */
+    statusReason: text("status_reason"),
+    /** The last check of the store's webhooks and key, made on a merchant's visit (never on a schedule). */
+    health: jsonb("health").$type(),
+    /** When the store last delivered a webhook we accepted. */
+    lastEventAt: timestamp("last_event_at", { withTimezone: true }),
     catalogWriteEnabled: boolean("catalog_write_enabled").notNull().default(false),
     catalogFieldMapping: jsonb("catalog_field_mapping").$type().notNull().default([]),
     catalogCursor: text("catalog_cursor"),
@@ -103,6 +109,8 @@ export const channelOrderExports = pgTable("channel_order_exports", {
     failureKind: text("failure_kind", { enum: ["definitive", "transient"] }),
     remoteOrderId: text("remote_order_id"),
     remoteUrl: text("remote_url"),
+    /** When the store's side of the order was last read by a read point catching up a missed delivery. */
+    remoteCheckedAt: timestamp("remote_checked_at", { withTimezone: true }),
     attempts: integer("attempts").notNull().default(0),
     lastError: text("last_error"),
     createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),