@porulle/plugin-channel-connector 0.65.1 → 0.67.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { type ChannelConnectorPluginOptions } from "./service.js";
 export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
-export { channelSyncHash, withDistinctVariantSkus } from "./service.js";
+export { channelOrderAddressSchema, channelSyncHash, withDistinctVariantSkus } from "./service.js";
+export { resolveLiveCredentials, withLiveCredentials } from "./live-credentials.js";
 export type { AbsentArchivePlan } from "./deletion-policy.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export type { MockChannelConnectorOptions } from "./mock-connector.js";
@@ -24,7 +25,7 @@ export type { CatalogFieldMapping, CatalogFieldMappingInput, CatalogFieldMapping
  */
 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, ChannelComplianceData, ChannelConnectorPluginOptions, ChannelStockLine, ExportState, PublicConnectedStore, ReconcileReport, } from "./service.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 declare function channelConnectorPlugin(options?: ChannelConnectorPluginOptions): import("@porulle/core").CommercePlugin;

package/dist/index.js

@@ -8,7 +8,8 @@ import { ChannelConnectorService, catalogPushConcurrencyKey, CHANNEL_INVENTORY_M
 import { buildHooks } from "./hooks.js";
 import { oauthStateEventId, signState, verifyState } from "./oauth-state.js";
 export { ABSENT_ARCHIVE_FLOOR, ABSENT_ARCHIVE_FRACTION, planAbsentArchives } from "./deletion-policy.js";
-export { channelSyncHash, withDistinctVariantSkus } from "./service.js";
+export { channelOrderAddressSchema, channelSyncHash, withDistinctVariantSkus } from "./service.js";
+export { resolveLiveCredentials, withLiveCredentials } from "./live-credentials.js";
 export { mockChannelConnector } from "./mock-connector.js";
 export { ChannelConnectorService, HERO_IMAGE_BYTE_CAP, selectImportImages, CATALOG_OUTBOUND_SUPPRESSION_WINDOW_MS, CATALOG_PUSH_BATCH_SIZES, CATALOG_PUSH_MAX_ATTEMPTS, canCatalogPushTransition, canExportTransition, catalogPushConcurrencyKey, catalogPushRetryDelayMs, CHANNEL_INVENTORY_MAX_ITEMS_PER_INVOCATION, isCatalogPushBreakerOpen, } from "./service.js";
 export { isValidCatalogMappingFieldPath, matchFieldPath, mergeCatalogFieldMapping, normalizeCatalogFieldMapping, compareCatalogFieldMappingSpecificity, providerCatalogFieldMappingDefaults, selectCatalogFieldMapping, validateCatalogMappingRow, } from "./catalog-field-mapping.js";
@@ -116,6 +117,18 @@ function oauthError(status, code, message) {
 function oauthRedirect(location) {
     return new Response(null, { status: 302, headers: { location } });
 }
+/** The merchant's browser lands on `postConnectRedirect` with the outcome in the query string. */
+function connectOutcome(postConnectRedirect, outcome) {
+    const url = new URL(postConnectRedirect);
+    if ("connected" in outcome) {
+        url.searchParams.set("connected", outcome.connected);
+    }
+    else {
+        url.searchParams.set("connect_error", outcome.error);
+        url.searchParams.set("connect_message", outcome.message);
+    }
+    return oauthRedirect(url.toString());
+}
 function callbackUri(raw, redirect, provider) {
     const request = raw.req.raw;
     const requestUrl = new URL(request.url);
@@ -269,6 +282,24 @@ export function channelConnectorPlugin(options = {}) {
                 return { output: result.value };
             },
         },
+        {
+            // One provider webhook delivery, applied off the request: Shopify gives a delivery five seconds,
+            // and a product re-read plus convergence is not bounded by that. Serialized per store, so two
+            // deliveries for one store apply in the order they were accepted.
+            slug: "channel/apply-webhook",
+            concurrency: { key: (input) => `webhook:${String(input.storeId)}` },
+            handler: async ({ input, ctx }) => {
+                const service = new ChannelConnectorService(ctx.db, ctx.services, options);
+                const result = await service.handleWebhook(String(input.orgId), String(input.storeId), {
+                    id: String(input.id),
+                    type: String(input.topic),
+                    data: input.data,
+                });
+                if (!result.ok)
+                    throw new Error(result.error);
+                return { output: { processed: true } };
+            },
+        },
         {
             slug: "channel/reap-exports",
             handler: async ({ input, ctx }) => {
@@ -286,7 +317,8 @@ export function channelConnectorPlugin(options = {}) {
         version: "1.0.0",
         permissions: [
             { scope: "channels:read", description: "Read connected stores and channel export status." },
-            { scope: "channels:manage", description: "Connect stores and retry channel order exports." },
+            { scope: "channels:manage", description: "Operate every store in the organization: backfills, pushes, conflicts, exports." },
+            { scope: "channels:connect", description: "Connect, reconnect and disconnect the caller's own stores." },
         ],
         schema: () => ({
             connectedStores,
@@ -311,10 +343,10 @@ export function channelConnectorPlugin(options = {}) {
             const channels = router("Channels", "/channels", ctx);
             channels.get("/oauth/{provider}/start")
                 .summary("Start channel OAuth onboarding")
-                .permission("channels:manage")
+                .permission("channels:connect")
                 .params(z.object({ provider: z.string().min(1) }))
                 .query(z.object({ shop: z.string().min(1).optional(), store: z.string().min(1).optional() }))
-                .handler(async ({ params, query, orgId, raw }) => {
+                .handler(async ({ params, query, orgId, actor, raw }) => {
                 const oauth = options.oauth;
                 if (!oauth?.stateSecret || !oauth.postConnectRedirect)
                     return oauthError(501, "OAUTH_NOT_CONFIGURED", "Channel OAuth is not configured.");
@@ -324,14 +356,25 @@ export function channelConnectorPlugin(options = {}) {
                     return oauthError(404, "CONNECTOR_NOT_FOUND", `No connector registered for provider "${provider}".`);
                 if (!connector.buildAuthUrl)
                     return oauthError(501, "OAUTH_UNSUPPORTED", `Connector "${provider}" does not support OAuth onboarding.`);
-                const storeDomain = String(query.shop ?? query.store ?? "");
+                // The callback arrives with no session of its own; the store is bound to the user who started
+                // here, carried in the signed state. A caller with no user (an API key) cannot start one.
+                const userId = actor?.userId;
+                if (!userId)
+                    return oauthError(403, "USER_REQUIRED", "Connecting a store needs a signed-in user.");
+                const claims = await service.connectClaims({ orgId, actor, raw });
+                if (!claims.ok)
+                    return connectOutcome(oauth.postConnectRedirect, { error: claims.code ?? "CONNECT_REFUSED", message: claims.error });
+                const typed = String(query.shop ?? query.store ?? "");
+                const storeDomain = connector.normalizeStoreDomain ? connector.normalizeStoreDomain(typed) : typed;
                 if (!storeDomain)
-                    return oauthError(400, "STORE_DOMAIN_REQUIRED", "The shop or store query parameter is required.");
+                    return connectOutcome(oauth.postConnectRedirect, { error: "INVALID_STORE_DOMAIN", message: `"${typed}" does not name a ${provider} store.` });
                 const state = signState({
                     provider,
                     orgId,
+                    userId,
+                    claims: claims.value,
                     shopDomain: storeDomain,
-                    exp: Math.floor(Date.now() / 1000) + 300,
+                    exp: Math.floor(Date.now() / 1000) + 600,
                     jti: crypto.randomUUID(),
                 }, oauth.stateSecret);
                 const redirect = callbackUri(raw, oauth.postConnectRedirect, provider);
@@ -343,7 +386,7 @@ export function channelConnectorPlugin(options = {}) {
                     scopes: [],
                 });
                 if (!authUrl.ok)
-                    return oauthError(422, authUrl.error.code, authUrl.error.message);
+                    return connectOutcome(oauth.postConnectRedirect, { error: authUrl.error.code, message: authUrl.error.message });
                 return oauthRedirect(authUrl.value);
             });
             const handleOAuthCallback = async ({ params, raw }) => {
@@ -359,12 +402,13 @@ export function channelConnectorPlugin(options = {}) {
                 const request = raw.req.raw;
                 const requestUrl = new URL(request.url);
                 const state = requestUrl.searchParams.get("state");
+                const refused = (error, message) => connectOutcome(oauth.postConnectRedirect, { error, message });
                 if (!state)
-                    return oauthError(403, "INVALID_OAUTH_STATE", "OAuth state is missing.");
+                    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), !landing);
+                const verified = verifyState(state, oauth.stateSecret, Math.floor(Date.now() / 1000));
                 if (!verified.ok || verified.value.provider !== provider)
-                    return oauthError(403, "INVALID_OAUTH_STATE", "OAuth state is invalid or expired.");
+                    return refused("INVALID_OAUTH_STATE", "The connection link expired; start again.");
                 if (landing)
                     return oauthRedirect(oauth.postConnectRedirect);
                 const [consumed] = await db.insert(processedWebhookEvents).values({
@@ -373,20 +417,20 @@ export function channelConnectorPlugin(options = {}) {
                     eventType: "oauth_state",
                 }).onConflictDoNothing().returning({ id: processedWebhookEvents.id });
                 if (!consumed)
-                    return oauthError(403, "OAUTH_STATE_REPLAYED", "OAuth state has already been used.");
+                    return refused("OAUTH_STATE_REPLAYED", "This connection link was already used; start again.");
                 const completed = await connector.completeAuth(request, { storeDomain: verified.value.shopDomain });
                 if (!completed.ok)
-                    return oauthError(400, completed.error.code, completed.error.message);
+                    return refused(completed.error.code, completed.error.message);
                 if (completed.value.storeDomain !== verified.value.shopDomain)
-                    return oauthError(400, "OAUTH_STORE_MISMATCH", "OAuth callback store does not match the signed state.");
+                    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 oauthError(422, connected.code ?? "STORE_CONNECTION_FAILED", connected.error);
-                return oauthRedirect(oauth.postConnectRedirect);
+                    return refused(connected.code ?? "STORE_CONNECTION_FAILED", connected.error);
+                return connectOutcome(oauth.postConnectRedirect, { connected: connected.value.id });
             };
             channels.get("/oauth/{provider}/callback")
                 .summary("Complete channel OAuth onboarding")
@@ -405,8 +449,8 @@ export function channelConnectorPlugin(options = {}) {
                 if (!store || !store.webhookSecret)
                     return context.json({ error: { code: "UNAUTHORIZED", message: "Webhook store is not available." } }, 401);
                 const connector = service.getConnector(store.provider);
-                if (!connector)
-                    return context.json({ error: { code: "UNAUTHORIZED", message: "Webhook provider is not configured." } }, 401);
+                if (!connector?.verifyWebhook)
+                    return context.json({ error: { code: "UNAUTHORIZED", message: "Webhook provider is not configured for per-store deliveries." } }, 401);
                 const verified = await connector.verifyWebhook(store, context.req.raw);
                 if (!verified.ok)
                     return context.json({ error: { code: "UNAUTHORIZED", message: "Invalid webhook signature." } }, 401);
@@ -422,50 +466,43 @@ export function channelConnectorPlugin(options = {}) {
                         ...(handled.value.redacted !== undefined ? { redacted: handled.value.redacted } : {}),
                     } });
             });
-            channels.post("/compliance/{provider}")
-                .summary("Receive a compliance webhook")
+            // 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
+            // declares. Verified, deduplicated on the provider's delivery id, and handed to a job per store:
+            // the answer must be quick, and the work is not.
+            channels.post("/app-webhooks/{provider}")
+                .summary("Receive a provider's app-level webhook")
                 .params(z.object({ provider: z.string().min(1) }))
                 .handler(async ({ params, raw }) => {
                 const context = raw;
                 const provider = params.provider;
                 const connector = service.getConnector(provider);
-                if (!connector)
-                    return context.json({ error: { code: "NOT_FOUND", message: `No connector registered for provider "${provider}".` } }, 404);
-                if (!connector.verifyAppWebhook)
-                    return context.json({ error: { code: "NOT_IMPLEMENTED", message: `Compliance webhook is not supported for provider "${provider}".` } }, 501);
+                if (!connector?.verifyAppWebhook)
+                    return context.json({ error: { code: "NOT_FOUND", message: `No app-level webhooks for provider "${provider}".` } }, 404);
                 const verified = await connector.verifyAppWebhook(context.req.raw);
                 if (!verified.ok)
                     return context.json({ error: { code: "UNAUTHORIZED", message: verified.error.message } }, 401);
-                const request = context.req.raw;
-                const eventId = request.headers.get("x-shopify-event-id") ?? createHash("sha256").update(`${verified.value.topic}:${verified.value.shopDomain}:${JSON.stringify(verified.value.data)}`).digest("hex");
-                const [inserted] = await db.insert(processedWebhookEvents).values({ eventId, provider, eventType: verified.value.topic }).onConflictDoNothing().returning({ id: processedWebhookEvents.id });
-                if (!inserted)
+                const event = verified.value;
+                const [marked] = await db.insert(processedWebhookEvents).values({ eventId: event.id, provider, eventType: event.topic }).onConflictDoNothing().returning({ id: processedWebhookEvents.id });
+                if (!marked)
                     return context.json({ data: { received: true, duplicate: true } });
-                const stores = await service.getStoresByDomain(verified.value.shopDomain);
-                if (stores.length === 0)
-                    return context.json({ data: { received: true } });
-                let redacted = 0;
-                let redactedSeen = false;
-                let complianceData;
-                for (const store of stores) {
-                    const handled = await service.handleWebhook(store.organizationId, store.id, { id: eventId, type: verified.value.topic, data: verified.value.data });
-                    if (!handled.ok)
-                        return context.json({ error: { code: "WEBHOOK_PROCESSING_FAILED", message: handled.error } }, 422);
-                    if (handled.value.redacted !== undefined) {
-                        redacted += handled.value.redacted;
-                        redactedSeen = true;
-                    }
-                    if (handled.value.data) {
-                        complianceData = complianceData
-                            ? { customer: complianceData.customer, exports: [...complianceData.exports, ...handled.value.data.exports] }
-                            : handled.value.data;
+                const stores = (await service.getStoresByDomain(event.shopDomain)).filter((store) => store.provider === provider);
+                const jobs = ctx.services.jobs;
+                try {
+                    for (const store of stores) {
+                        await jobs.enqueue("channel/apply-webhook", { orgId: store.organizationId, storeId: store.id, id: event.id, topic: event.topic, data: event.data }, {
+                            organizationId: store.organizationId,
+                            concurrencyKey: `webhook:${store.id}`,
+                            supersedes: false,
+                        });
                     }
                 }
-                return context.json({ data: {
-                        received: true,
-                        ...(complianceData ? { data: complianceData } : {}),
-                        ...(redactedSeen ? { redacted } : {}),
-                    } });
+                catch (error) {
+                    // Not accepted: forget the delivery so the provider's retry is applied, not dropped as a duplicate.
+                    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, stores: stores.length } });
             });
             channels.post("/stores")
                 .summary("Connect a channel store")
@@ -476,8 +513,9 @@ export function channelConnectorPlugin(options = {}) {
                 storeDomain: z.string().min(1),
                 webhookSecret: z.string().min(1).optional(),
             }))
-                .handler(async ({ input, orgId }) => {
-                return unwrap(await service.connectStore(orgId, input));
+                .handler(async ({ input, orgId, actor, raw }) => {
+                const claims = unwrap(await service.connectClaims({ orgId, actor, raw }));
+                return unwrap(await service.connectStore(orgId, input, { orgId, userId: actor?.userId ?? null, claims, raw }));
             });
             channels.get("/stores")
                 .summary("List connected channel stores")
@@ -486,7 +524,7 @@ export function channelConnectorPlugin(options = {}) {
             channels.get("/stores/{id}")
                 .summary("Get a connected channel store")
                 .permission("channels:read")
-                .handler(async ({ params, orgId }) => unwrap(await service.getStore(orgId, params.id)));
+                .handler(async ({ params, orgId, actor, raw }) => unwrap(await service.getStore(orgId, params.id, { orgId, actor, raw })));
             channels.get("/stores/{storeId}/catalog-write")
                 .summary("Get catalog write settings for a channel store")
                 .permission("channels:manage")
@@ -509,7 +547,10 @@ export function channelConnectorPlugin(options = {}) {
             channels.get("/stores/{storeId}/reconcile-status")
                 .summary("Get channel reconciliation status")
                 .permission("channels:read")
-                .handler(async ({ params, orgId }) => unwrap(await service.getReconcileStatus(orgId, params.storeId)));
+                .handler(async ({ params, orgId, actor, raw }) => {
+                unwrap(await service.reachableStore(orgId, params.storeId, { orgId, actor, raw }));
+                return unwrap(await service.getReconcileStatus(orgId, params.storeId));
+            });
             channels.get("/conflicts")
                 .summary("List channel catalog conflicts")
                 .permission("channels:read")
@@ -581,8 +622,8 @@ export function channelConnectorPlugin(options = {}) {
             });
             channels.post("/stores/{id}/disconnect")
                 .summary("Disconnect a channel store")
-                .permission("channels:manage")
-                .handler(async ({ params, orgId }) => unwrap(await service.disconnectStore(orgId, params.id)));
+                .permission("channels:connect")
+                .handler(async ({ params, orgId, actor, raw }) => unwrap(await service.disconnectStore(orgId, params.id, { orgId, actor, raw })));
             channels.get("/exports/failed")
                 .summary("List failed channel order exports")
                 .permission("channels:read")

package/dist/live-credentials.d.ts

@@ -0,0 +1,24 @@
+import type { ChannelConnector, ChannelConnectorError, ChannelStore, PluginDb, Result } from "@porulle/core";
+/**
+ * The store with credentials good for the next call.
+ *
+ * A provider that grants EXPIRING credentials (Shopify: a one-hour access token and a rotating
+ * refresh token) says so through `liveCredentials`; this asks it and persists what it returns.
+ *
+ * Persisting is a compare-and-swap on the credentials the call started from. Two Workers that both
+ * find the token expiring both refresh; the first write wins and the second, finding the row moved,
+ * adopts what the first wrote rather than overwriting a newer refresh token with its own. (Shopify
+ * keeps a presented refresh token usable until the app presents the newer one, and a retired access
+ * token valid until its own expiry, so the loser's in-flight call still succeeds.)
+ *
+ * A refusal that is not retriable means the grant is gone — the merchant uninstalled, or the refresh
+ * token lapsed. The store is then marked `error`, so it reads as "reconnect" instead of failing every
+ * later call with a credential error nobody is shown.
+ */
+export declare function resolveLiveCredentials(connector: ChannelConnector, db: PluginDb, store: ChannelStore): Promise<Result<ChannelStore, ChannelConnectorError>>;
+/**
+ * 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.
+ */
+export declare function withLiveCredentials(connector: ChannelConnector, db: PluginDb): ChannelConnector;

package/dist/live-credentials.js

@@ -0,0 +1,71 @@
+import { Err, Ok } from "@porulle/core";
+import { and, eq, sql } from "@porulle/core/drizzle";
+import { connectedStores } from "./schema.js";
+/**
+ * The store with credentials good for the next call.
+ *
+ * A provider that grants EXPIRING credentials (Shopify: a one-hour access token and a rotating
+ * refresh token) says so through `liveCredentials`; this asks it and persists what it returns.
+ *
+ * Persisting is a compare-and-swap on the credentials the call started from. Two Workers that both
+ * find the token expiring both refresh; the first write wins and the second, finding the row moved,
+ * adopts what the first wrote rather than overwriting a newer refresh token with its own. (Shopify
+ * keeps a presented refresh token usable until the app presents the newer one, and a retired access
+ * token valid until its own expiry, so the loser's in-flight call still succeeds.)
+ *
+ * A refusal that is not retriable means the grant is gone — the merchant uninstalled, or the refresh
+ * token lapsed. The store is then marked `error`, so it reads as "reconnect" instead of failing every
+ * later call with a credential error nobody is shown.
+ */
+export async function resolveLiveCredentials(connector, db, store) {
+    if (!connector.liveCredentials)
+        return Ok(store);
+    const answer = await connector.liveCredentials(store);
+    if (!answer.ok) {
+        if (answer.error.retriable !== true) {
+            await db.update(connectedStores).set({ status: "error", updatedAt: new Date() }).where(eq(connectedStores.id, store.id));
+        }
+        return answer;
+    }
+    if (answer.value === null)
+        return Ok(store);
+    const swapped = await db.update(connectedStores)
+        .set({ credentials: answer.value, updatedAt: new Date() })
+        .where(and(eq(connectedStores.id, store.id), sql `${connectedStores.credentials} = ${JSON.stringify(store.credentials)}::jsonb`))
+        .returning({ id: connectedStores.id });
+    if (swapped.length > 0)
+        return Ok({ ...store, credentials: answer.value });
+    const [current] = await db.select({ credentials: connectedStores.credentials }).from(connectedStores).where(eq(connectedStores.id, store.id));
+    if (!current)
+        return Err({ code: "STORE_NOT_FOUND", message: `Connected store ${store.id} no longer exists.`, retriable: false });
+    return Ok({ ...store, credentials: current.credentials });
+}
+/**
+ * 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.
+ */
+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)
+            return current;
+        return call.call(connector, current.value, ...args);
+    };
+    return {
+        ...connector,
+        importCatalog: around(connector.importCatalog),
+        fetchInventory: around(connector.fetchInventory),
+        pushOrder: around(connector.pushOrder),
+        fetchOrderStatus: around(connector.fetchOrderStatus),
+        refundExecute: around(connector.refundExecute),
+        ...(connector.fetchInventoryPage ? { fetchInventoryPage: around(connector.fetchInventoryPage) } : {}),
+        ...(connector.fetchCatalogItems ? { fetchCatalogItems: around(connector.fetchCatalogItems) } : {}),
+        ...(connector.fetchStoreProfile ? { fetchStoreProfile: around(connector.fetchStoreProfile) } : {}),
+        ...(connector.pushCatalog ? { pushCatalog: around(connector.pushCatalog) } : {}),
+        ...(connector.reserve ? { reserve: around(connector.reserve) } : {}),
+        ...(connector.registerWebhooks ? { registerWebhooks: around(connector.registerWebhooks) } : {}),
+    };
+}

package/dist/oauth-state.d.ts

@@ -1,6 +1,10 @@
 export interface OAuthStatePayload {
     provider: string;
     orgId: string;
+    /** The signed-in user who started the connection: the callback arrives with no session of its own. */
+    userId: string;
+    /** The consumer's connect claims, resolved at start. */
+    claims: Record<string, string>;
     shopDomain: string;
     exp: number;
     jti: string;
@@ -13,5 +17,10 @@ export type OAuthStateResult = {
     error: string;
 };
 export declare function signState(payload: OAuthStatePayload, secret: string): string;
-export declare function verifyState(state: string, secret: string, now?: number, consume?: boolean): OAuthStateResult;
+/**
+ * Checks the signature and expiry. Single use is NOT decided here: an in-memory record of used states
+ * would forget on every Worker isolate, so the callback records each state's `jti` in the database and
+ * refuses a second use there.
+ */
+export declare function verifyState(state: string, secret: string, now?: number): OAuthStateResult;
 export declare function oauthStateEventId(jti: string): string;

package/dist/oauth-state.js

@@ -1,5 +1,4 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
-const consumedJtis = new Map();
 function encodeText(value) {
     return Buffer.from(value, "utf8").toString("base64url");
 }
@@ -23,7 +22,12 @@ export function signState(payload, secret) {
     const encodedPayload = encodeText(JSON.stringify(payload));
     return `${encodedPayload}.${encodeBytes(signature(encodedPayload, secret))}`;
 }
-export function verifyState(state, secret, now = Math.floor(Date.now() / 1000), consume = true) {
+/**
+ * Checks the signature and expiry. Single use is NOT decided here: an in-memory record of used states
+ * would forget on every Worker isolate, so the callback records each state's `jti` in the database and
+ * refuses a second use there.
+ */
+export function verifyState(state, secret, now = Math.floor(Date.now() / 1000)) {
     if (!secret)
         return { ok: false, error: "OAuth state secret is required." };
     const parts = state.split(".");
@@ -56,6 +60,7 @@ export function verifyState(state, secret, now = Math.floor(Date.now() / 1000),
     const exp = candidate.exp;
     if (typeof candidate.provider !== "string" ||
         typeof candidate.orgId !== "string" ||
+        typeof candidate.userId !== "string" ||
         typeof candidate.shopDomain !== "string" ||
         typeof candidate.jti !== "string" ||
         typeof exp !== "number" ||
@@ -63,14 +68,10 @@ export function verifyState(state, secret, now = Math.floor(Date.now() / 1000),
         return { ok: false, error: "Malformed OAuth state payload." };
     if (exp <= now)
         return { ok: false, error: "OAuth state has expired." };
-    for (const [jti, expiresAt] of consumedJtis) {
-        if (expiresAt <= now)
-            consumedJtis.delete(jti);
+    const claims = candidate.claims;
+    if (typeof claims !== "object" || claims === null || Object.values(claims).some((value) => typeof value !== "string")) {
+        return { ok: false, error: "Malformed OAuth state payload." };
     }
-    if (consume && consumedJtis.has(candidate.jti))
-        return { ok: false, error: "OAuth state has already been used." };
-    if (consume)
-        consumedJtis.set(candidate.jti, exp);
     return { ok: true, value: candidate };
 }
 export function oauthStateEventId(jti) {

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-import type { ChannelPushCatalogItem } from "@porulle/core";
+import type { ChannelOrderAddress, ChannelPushCatalogItem } from "@porulle/core";
 import type { CatalogFieldMapping } from "./catalog-field-mapping.js";
 export declare const connectedStores: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
     name: "connected_stores";
@@ -1074,7 +1074,7 @@ export declare const channelOrderExports: import("drizzle-orm/pg-core/table").Pg
             data: {
                 name: string;
                 email: string;
-                shippingAddress: Record<string, unknown>;
+                shippingAddress: ChannelOrderAddress;
             };
             driverParam: unknown;
             notNull: false;
@@ -1090,7 +1090,7 @@ export declare const channelOrderExports: import("drizzle-orm/pg-core/table").Pg
             $type: {
                 name: string;
                 email: string;
-                shippingAddress: Record<string, unknown>;
+                shippingAddress: ChannelOrderAddress;
             };
         }>;
         state: import("@porulle/core/drizzle").PgColumn<{