@porulle/plugin-channel-connector 0.73.3 → 0.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.73.3",
+  "version": "0.74.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -22,7 +22,7 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.73.3"
+    "@porulle/core": "0.74.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",

package/src/index.ts

@@ -260,6 +260,7 @@ export type {
   ChannelRefundEvent,
   ChannelRefundRequest,
   ConnectedStore,
+  StoreHealth,
 } from "./schema.js";
 
 function unwrap<T>(result: PluginResult<T>): T {
@@ -312,6 +313,14 @@ function callbackUri(raw: unknown, redirect: string, provider: string): string {
   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: ChannelConnectorPluginOptions = {}) {
   const jobs: TaskDefinition[] = [
     {
@@ -470,7 +479,33 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
           data: input.data,
         });
         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: Record<string, unknown>) => `webhook:${String(input.storeId)}` },
+      handler: async ({ input, ctx }: { input: Record<string, unknown>; ctx: import("@porulle/core").TaskContext }) => {
+        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: Record<string, unknown>) => `connect:${String(input.storeId)}` },
+      handler: async ({ input, ctx }: { input: Record<string, unknown>; ctx: import("@porulle/core").TaskContext }) => {
+        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 } };
       },
     },
     {
@@ -564,6 +599,11 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
           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 }: { params: Record<string, string>; raw: unknown }) => {
         const oauth = options.oauth;
         if (!oauth?.stateSecret || !oauth.postConnectRedirect) return oauthError(501, "OAUTH_NOT_CONFIGURED", "Channel OAuth is not configured.");
@@ -573,29 +613,45 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
         if (!connector.completeAuth) return oauthError(501, "OAUTH_UNSUPPORTED", `Connector "${provider}" does not support OAuth onboarding.`);
         const request = (raw as { req: { raw: Request } }).req.raw;
         const requestUrl = new URL(request.url);
+        const posted = request.method === "POST";
         const state = requestUrl.searchParams.get("state");
-        const refused = (error: string, message: string): Response => 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: string, message: string, status = 400): Response => 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 });
+        if (!consumed) 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 as JobsAdapter).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")
@@ -608,26 +664,38 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
         .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 as { req: { raw: Request; header(name: string): string | undefined }; json(data: unknown, status?: number): Response };
-          const storeId = params.storeId!;
-          const [store] = await db.select().from(connectedStores).where(eq(connectedStores.id, storeId));
-          if (!store || !store.webhookSecret) return context.json({ error: { code: "UNAUTHORIZED", message: "Webhook store is not available." } }, 401);
+          const context = raw as { req: { raw: Request }; json(data: unknown, status?: number): Response };
+          const [store] = await db.select().from(connectedStores).where(eq(connectedStores.id, params.storeId!));
+          if (!store || !store.webhookSecret) 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);
+          if (!connector?.verifyWebhook) 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) 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 } : {}),
-          } });
+          // 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 } });
+          try {
+            await (ctx.services.jobs as JobsAdapter).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
@@ -802,6 +870,11 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
           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 }: ChannelRouteContext) => unwrap(await service.checkStoreHealth(orgId, params.id!, { orgId, actor, raw })));
+
       channels.post("/stores/{id}/disconnect")
         .summary("Disconnect a channel store")
         .permission("channels:connect")

package/src/live-credentials.ts

@@ -41,24 +41,37 @@ export async function resolveLiveCredentials(connector: ChannelConnector, db: Pl
 
 type StoreCall<A extends unknown[], T> = (store: ChannelStore, ...args: A) => Promise<Result<T, ChannelConnectorError>>;
 
+/** 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: PluginDb, storeId: string): Promise<void> {
+  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: ChannelConnector, db: PluginDb): ChannelConnector {
-  if (!connector.liveCredentials) return connector;
   const around = <A extends unknown[], T>(call: StoreCall<A, T>): StoreCall<A, T> => async (store, ...args) => {
     const current = await resolveLiveCredentials(connector, db, store);
     if (!current.ok) return current;
     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,
@@ -73,6 +86,11 @@ export function withLiveCredentials(connector: ChannelConnector, db: PluginDb):
     ...(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/src/mock-connector.ts

@@ -4,8 +4,10 @@ import {
   Ok,
   defineChannelConnector,
 } from "@porulle/core";
+import { z } from "zod";
 import type {
   ChannelCatalogItem,
+  ChannelEvent,
   ChannelConnectorError,
   ChannelInventoryLevel,
   ChannelOrderSlice,
@@ -76,6 +78,28 @@ const defaultCatalog: ChannelCatalogItem[] = [{
   }],
 }];
 
+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()) }),
+]) satisfies z.ZodType<ChannelEvent>;
+
 export function mockChannelConnector(options: MockChannelConnectorOptions = {}) {
   const orders = new Map<string, ChannelOrderSlice>();
   const catalog = new Map<string, ChannelPushCatalogItem>();
@@ -92,6 +116,16 @@ export function mockChannelConnector(options: MockChannelConnectorOptions = {})
     async importCatalog(_store?: ChannelStore) {
       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/src/schema.ts

@@ -14,6 +14,17 @@ import type { ChannelOrderAddress, ChannelPushCatalogItem, FieldPath } from "@po
 import { sellableEntities } from "@porulle/core/schema";
 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 const connectedStores = pgTable(
   "connected_stores",
   {
@@ -22,9 +33,15 @@ export const connectedStores = pgTable(
     provider: text("provider").notNull(),
     credentials: jsonb("credentials").$type<Record<string, unknown>>().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<StoreHealth>(),
+    /** 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<CatalogFieldMapping>().notNull().default([]),
     catalogCursor: text("catalog_cursor"),
@@ -152,6 +169,8 @@ export const channelOrderExports = pgTable(
     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(),