@porulle/plugin-channel-connector 0.66.0 → 0.67.0

package/dist/index.d.ts

@@ -25,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, AfterStoreConnected, BindConnectedStore, ChannelComplianceData, ChannelConnectorPluginOptions, ConfineStores, OnStoreCatalogChanged, StoreConnectActor, StoreReadContext, 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

@@ -361,6 +361,9 @@ export function channelConnectorPlugin(options = {}) {
                 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)
@@ -369,6 +372,7 @@ export function channelConnectorPlugin(options = {}) {
                     provider,
                     orgId,
                     userId,
+                    claims: claims.value,
                     shopDomain: storeDomain,
                     exp: Math.floor(Date.now() / 1000) + 600,
                     jti: crypto.randomUUID(),
@@ -423,7 +427,7 @@ export function channelConnectorPlugin(options = {}) {
                     provider,
                     storeDomain: verified.value.shopDomain,
                     credentials: completed.value.credentials,
-                }, { orgId: verified.value.orgId, userId: verified.value.userId });
+                }, { 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 });
@@ -510,7 +514,8 @@ export function channelConnectorPlugin(options = {}) {
                 webhookSecret: z.string().min(1).optional(),
             }))
                 .handler(async ({ input, orgId, actor, raw }) => {
-                return unwrap(await service.connectStore(orgId, input, { orgId, userId: actor?.userId ?? null, 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")

package/dist/oauth-state.d.ts

@@ -3,6 +3,8 @@ export interface OAuthStatePayload {
     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;

package/dist/oauth-state.js

@@ -68,6 +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." };
+    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." };
+    }
     return { ok: true, value: candidate };
 }
 export function oauthStateEventId(jti) {

package/dist/service.d.ts

@@ -109,9 +109,20 @@ export type ConfineStores = (context: StoreReadContext) => Promise<readonly stri
 export interface StoreConnectActor {
     orgId: string;
     userId: string | null;
+    /**
+     * What the consumer's {@link ConnectClaims} resolved when the connection started — e.g. which of
+     * the user's vendors the store is for. Carried in the signed OAuth state, so the callback, which has
+     * no session or headers of its own, binds the store to exactly what was chosen at the start.
+     */
+    claims: Readonly<Record<string, string>>;
     /** Core's request escape hatch when the connect is a request; absent on the OAuth callback. */
     raw?: unknown;
 }
+/**
+ * Resolves, from the request that STARTS a connection, the facts the consumer needs to bind the store
+ * later. Throw to refuse the start. Runs for OAuth start and for `POST /stores`.
+ */
+export type ConnectClaims = (context: StoreReadContext) => Promise<Record<string, string>> | Record<string, string>;
 /**
  * Binds a just-connected store to whatever the consumer means by an owner, INSIDE the transaction
  * that wrote the store row — so a store and its binding commit together or not at all. Throw to
@@ -127,6 +138,7 @@ export type AfterStoreConnected = (input: {
     store: ConnectedStore;
     actor: StoreConnectActor;
     connector: ChannelConnector;
+    services: Record<string, unknown>;
 }) => Promise<void>;
 /** Entities a provider webhook just created or changed, converged; the host projects them. */
 export type OnStoreCatalogChanged = (input: {
@@ -154,6 +166,8 @@ export interface ChannelConnectorPluginOptions {
      * unaffected.
      */
     confineStores?: ConfineStores;
+    /** See {@link ConnectClaims}. Absent, a connection carries no claims. */
+    connectClaims?: ConnectClaims;
     /** See {@link BindConnectedStore}. */
     bindConnectedStore?: BindConnectedStore;
     /** See {@link AfterStoreConnected}. */
@@ -495,6 +509,8 @@ export declare class ChannelConnectorService {
     }, actor: StoreConnectActor): Promise<PluginResult<PublicConnectedStore>>;
     /** The store with credentials good for a call the host makes itself, e.g. its own Admin API write. */
     liveStore(orgId: string, storeId: string): Promise<PluginResult<ChannelStore>>;
+    /** The consumer's claims for a connection starting from this request. See {@link ConnectClaims}. */
+    connectClaims(context: StoreReadContext): Promise<PluginResult<Record<string, string>>>;
     /** The caller's allow-list, or null for unconfined. See {@link ConfineStores}. */
     private allowedStores;
     /** NOT_FOUND for a store outside the caller's set, exactly as for one that does not exist. */

package/dist/service.js

@@ -2269,7 +2269,7 @@ export class ChannelConnectorService {
         }
         if (this.options.afterStoreConnected) {
             try {
-                await this.options.afterStoreConnected({ store, actor, connector });
+                await this.options.afterStoreConnected({ store, actor, connector, services: this.services });
             }
             catch (error) {
                 return PluginErr(error instanceof Error ? error.message : "The store connected but its follow-on work failed.", "AFTER_CONNECT_FAILED");
@@ -2288,6 +2288,17 @@ export class ChannelConnectorService {
         const live = await resolveLiveCredentials(connector, this.db, store);
         return live.ok ? Ok(live.value) : PluginErr(live.error.message, live.error.code);
     }
+    /** The consumer's claims for a connection starting from this request. See {@link ConnectClaims}. */
+    async connectClaims(context) {
+        if (!this.options.connectClaims)
+            return Ok({});
+        try {
+            return Ok(await this.options.connectClaims(context));
+        }
+        catch (error) {
+            return PluginErr(error instanceof Error ? error.message : "The connection could not be started.", error instanceof CommerceNotFoundError ? "NOT_FOUND" : "CONNECT_REFUSED");
+        }
+    }
     /** The caller's allow-list, or null for unconfined. See {@link ConfineStores}. */
     async allowedStores(orgId, context) {
         return this.options.confineStores ? await this.options.confineStores(context ?? { orgId, actor: null, raw: undefined }) : null;

package/package.json

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

package/src/index.ts

@@ -238,6 +238,7 @@ export type {
   ChannelComplianceData,
   ChannelConnectorPluginOptions,
   ConfineStores,
+  ConnectClaims,
   OnStoreCatalogChanged,
   StoreConnectActor,
   StoreReadContext,
@@ -531,6 +532,8 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
           // 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 as { shop?: string; store?: string }).shop ?? (query as { store?: string }).store ?? "");
           const 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.` });
@@ -538,6 +541,7 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
             provider,
             orgId,
             userId,
+            claims: claims.value,
             shopDomain: storeDomain,
             exp: Math.floor(Date.now() / 1000) + 600,
             jti: crypto.randomUUID(),
@@ -583,7 +587,7 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
           provider,
           storeDomain: verified.value.shopDomain,
           credentials: completed.value.credentials,
-        }, { orgId: verified.value.orgId, userId: verified.value.userId });
+        }, { 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 });
       };
@@ -665,6 +669,7 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
           webhookSecret: z.string().min(1).optional(),
         }))
         .handler(async ({ input, orgId, actor, raw }: ChannelRouteContext) => {
+          const claims = unwrap(await service.connectClaims({ orgId, actor, raw }));
           return unwrap(await service.connectStore(
             orgId,
             input as {
@@ -673,7 +678,7 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
               storeDomain: string;
               webhookSecret?: string;
             },
-            { orgId, userId: actor?.userId ?? null, raw },
+            { orgId, userId: actor?.userId ?? null, claims, raw },
           ));
         });
 

package/src/oauth-state.ts

@@ -5,6 +5,8 @@ export interface OAuthStatePayload {
   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;
@@ -86,6 +88,10 @@ export function verifyState(
     !Number.isInteger(exp)
   ) return { ok: false, error: "Malformed OAuth state payload." };
   if (exp <= now) return { ok: false, error: "OAuth state has expired." };
+  const claims: unknown = (candidate as { claims?: unknown }).claims;
+  if (typeof claims !== "object" || claims === null || Object.values(claims).some((value) => typeof value !== "string")) {
+    return { ok: false, error: "Malformed OAuth state payload." };
+  }
 
   return { ok: true, value: candidate as OAuthStatePayload };
 }

package/src/service.ts

@@ -254,10 +254,22 @@ export type ConfineStores = (context: StoreReadContext) => Promise<readonly stri
 export interface StoreConnectActor {
   orgId: string;
   userId: string | null;
+  /**
+   * What the consumer's {@link ConnectClaims} resolved when the connection started — e.g. which of
+   * the user's vendors the store is for. Carried in the signed OAuth state, so the callback, which has
+   * no session or headers of its own, binds the store to exactly what was chosen at the start.
+   */
+  claims: Readonly<Record<string, string>>;
   /** Core's request escape hatch when the connect is a request; absent on the OAuth callback. */
   raw?: unknown;
 }
 
+/**
+ * Resolves, from the request that STARTS a connection, the facts the consumer needs to bind the store
+ * later. Throw to refuse the start. Runs for OAuth start and for `POST /stores`.
+ */
+export type ConnectClaims = (context: StoreReadContext) => Promise<Record<string, string>> | Record<string, string>;
+
 /**
  * Binds a just-connected store to whatever the consumer means by an owner, INSIDE the transaction
  * that wrote the store row — so a store and its binding commit together or not at all. Throw to
@@ -266,7 +278,7 @@ export interface StoreConnectActor {
 export type BindConnectedStore = (input: { db: PluginDb; store: ConnectedStore; actor: StoreConnectActor }) => Promise<void>;
 
 /** Work that follows a committed connection: the first import, provider-attested facts, keys. */
-export type AfterStoreConnected = (input: { store: ConnectedStore; actor: StoreConnectActor; connector: ChannelConnector }) => Promise<void>;
+export type AfterStoreConnected = (input: { store: ConnectedStore; actor: StoreConnectActor; connector: ChannelConnector; services: Record<string, unknown> }) => Promise<void>;
 
 /** Entities a provider webhook just created or changed, converged; the host projects them. */
 export type OnStoreCatalogChanged = (input: { orgId: string; storeId: string; entityIds: string[]; convergence: CatalogPageConvergence }) => Promise<void>;
@@ -288,6 +300,8 @@ export interface ChannelConnectorPluginOptions {
    * unaffected.
    */
   confineStores?: ConfineStores;
+  /** See {@link ConnectClaims}. Absent, a connection carries no claims. */
+  connectClaims?: ConnectClaims;
   /** See {@link BindConnectedStore}. */
   bindConnectedStore?: BindConnectedStore;
   /** See {@link AfterStoreConnected}. */
@@ -3165,7 +3179,7 @@ export class ChannelConnectorService {
     }
     if (this.options.afterStoreConnected) {
       try {
-        await this.options.afterStoreConnected({ store, actor, connector });
+        await this.options.afterStoreConnected({ store, actor, connector, services: this.services });
       } catch (error) {
         return PluginErr(error instanceof Error ? error.message : "The store connected but its follow-on work failed.", "AFTER_CONNECT_FAILED");
       }
@@ -3183,6 +3197,16 @@ export class ChannelConnectorService {
     return live.ok ? Ok(live.value) : PluginErr(live.error.message, live.error.code);
   }
 
+  /** The consumer's claims for a connection starting from this request. See {@link ConnectClaims}. */
+  async connectClaims(context: StoreReadContext): Promise<PluginResult<Record<string, string>>> {
+    if (!this.options.connectClaims) return Ok({});
+    try {
+      return Ok(await this.options.connectClaims(context));
+    } catch (error) {
+      return PluginErr(error instanceof Error ? error.message : "The connection could not be started.", error instanceof CommerceNotFoundError ? "NOT_FOUND" : "CONNECT_REFUSED");
+    }
+  }
+
   /** The caller's allow-list, or null for unconfined. See {@link ConfineStores}. */
   private async allowedStores(orgId: string, context: StoreReadContext | undefined): Promise<readonly string[] | null> {
     return this.options.confineStores ? await this.options.confineStores(context ?? { orgId, actor: null, raw: undefined }) : null;