@porulle/plugin-channel-connector 0.42.0 → 0.43.0

package/dist/index.js

@@ -529,7 +529,7 @@ export function channelConnectorPlugin(options = {}) {
             channels.get("/stores")
                 .summary("List connected channel stores")
                 .permission("channels:read")
-                .handler(async ({ orgId }) => unwrap(await service.listStores(orgId)));
+                .handler(async ({ orgId, actor, raw }) => unwrap(await service.listStores(orgId, { orgId, actor, raw })));
             channels.get("/stores/{id}")
                 .summary("Get a connected channel store")
                 .permission("channels:read")

package/dist/service.d.ts

@@ -84,8 +84,38 @@ export interface ChannelComplianceData {
         customerData: NonNullable<ChannelOrderExport["customerData"]>;
     }>;
 }
+/**
+ * What a consumer is allowed to read, resolved per request.
+ *
+ * Returning `null` means "do not confine" and is the default — every existing consumer keeps the
+ * organization-wide behaviour. An array is the complete set of store ids this caller may see, and
+ * **`[]` means none**, not "no filter".
+ *
+ * It takes IDS rather than a tenant, deliberately. `vendor`, `seller`, `team` are models a consumer
+ * owns; this package is generic commerce and acquiring one of them here would push a marketplace
+ * concept into every deployment that has no such thing. The consumer resolves the meaning and hands
+ * back the answer.
+ */
+export type ConfineStoreReads = (context: StoreReadContext) => Promise<readonly string[] | null> | readonly string[] | null;
+/** What a consumer needs to resolve the caller. `raw` is core's documented request escape hatch. */
+export interface StoreReadContext {
+    orgId: string;
+    actor: {
+        userId: string | null;
+        [key: string]: unknown;
+    } | null;
+    raw: unknown;
+}
 export interface ChannelConnectorPluginOptions {
     connectors?: ChannelConnector[];
+    /**
+     * Confines store reads to a set the consumer chooses. See {@link ConfineStoreReads}.
+     *
+     * Absent by default, because narrowing an existing read for every deployment would be a breaking
+     * change to a published package. A consumer that needs confinement opts in; one that does not is
+     * unaffected.
+     */
+    confineStoreReads?: ConfineStoreReads;
     oauth?: {
         stateSecret: string;
         postConnectRedirect: string;
@@ -241,7 +271,7 @@ export declare class ChannelConnectorService {
     disconnectStore(orgId: string, id: string): Promise<PluginResult<PublicConnectedStore>>;
     disconnectStoreSystem(orgId: string, id: string, redactDomain?: boolean): Promise<PluginResult<PublicConnectedStore>>;
     getStore(orgId: string, id: string): Promise<PluginResult<PublicConnectedStore>>;
-    listStores(orgId: string): Promise<PluginResult<PublicConnectedStore[]>>;
+    listStores(orgId: string, context?: StoreReadContext): Promise<PluginResult<PublicConnectedStore[]>>;
     validateLineStock(orgId: string, lines: ChannelStockLine[], timeoutMs?: number): Promise<void>;
     importCatalog(orgId: string, storeId: string, actor: Actor, options: {
         maxItems: number;

package/dist/service.js

@@ -1612,11 +1612,25 @@ export class ChannelConnectorService {
             return PluginErr("Connected store not found.", "NOT_FOUND");
         return Ok(redactStore(store));
     }
-    async listStores(orgId) {
-        const rows = await this.db
-            .select()
-            .from(connectedStores)
-            .where(eq(connectedStores.organizationId, orgId));
+    async listStores(orgId, context) {
+        const allowed = this.options.confineStoreReads
+            ? await this.options.confineStoreReads(context ?? { orgId, actor: null, raw: undefined })
+            : null;
+        // An empty allow-list means the caller may read NOTHING, stated here rather than left to the
+        // query builder.
+        //
+        // MEASURED, because the first version of this comment claimed the guard was load-bearing and it
+        // is not: removing this line leaves every row in `confine-store-reads.test.ts` green, so drizzle
+        // already turns `inArray(id, [])` into a predicate that matches nothing. The guard is therefore
+        // the CONTRACT rather than the rescue — `[]` means none, whatever the builder does with an empty
+        // array on some future dialect or version. Worth keeping for that reason and not worth claiming
+        // more for: the row that covers this case is really watching drizzle, not this line.
+        if (allowed !== null && allowed.length === 0)
+            return Ok([]);
+        const predicate = allowed === null
+            ? eq(connectedStores.organizationId, orgId)
+            : and(eq(connectedStores.organizationId, orgId), inArray(connectedStores.id, [...allowed]));
+        const rows = await this.db.select().from(connectedStores).where(predicate);
         return Ok(rows.map(redactStore));
     }
     async validateLineStock(orgId, lines, timeoutMs = 3_000) {

package/package.json

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

package/src/index.ts

@@ -44,6 +44,13 @@ type ChannelRouteContext = {
   params: Record<string, string>;
   orgId: string;
   actor: { userId: string | null } | null;
+  /**
+   * Core's documented request escape hatch, already present on `RouteHandlerContext` and simply
+   * never declared here. Read by `confineStoreReads` so a consumer can resolve the caller from the
+   * request — core's `actor.vendorId` cannot serve that purpose: core sources it from a column on
+   * `user` that this deployment never writes, and sets it to `null` outright for API-key actors.
+   */
+  raw?: unknown;
 };
 
 export { mockChannelConnector } from "./mock-connector.js";
@@ -655,7 +662,8 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
       channels.get("/stores")
         .summary("List connected channel stores")
         .permission("channels:read")
-        .handler(async ({ orgId }: ChannelRouteContext) => unwrap(await service.listStores(orgId)));
+        .handler(async ({ orgId, actor, raw }: ChannelRouteContext) =>
+          unwrap(await service.listStores(orgId, { orgId, actor, raw })));
 
       channels.get("/stores/{id}")
         .summary("Get a connected channel store")

package/src/service.ts

@@ -214,8 +214,37 @@ export interface ChannelComplianceData {
   }>;
 }
 
+/**
+ * What a consumer is allowed to read, resolved per request.
+ *
+ * Returning `null` means "do not confine" and is the default — every existing consumer keeps the
+ * organization-wide behaviour. An array is the complete set of store ids this caller may see, and
+ * **`[]` means none**, not "no filter".
+ *
+ * It takes IDS rather than a tenant, deliberately. `vendor`, `seller`, `team` are models a consumer
+ * owns; this package is generic commerce and acquiring one of them here would push a marketplace
+ * concept into every deployment that has no such thing. The consumer resolves the meaning and hands
+ * back the answer.
+ */
+export type ConfineStoreReads = (context: StoreReadContext) => Promise<readonly string[] | null> | readonly string[] | null;
+
+/** What a consumer needs to resolve the caller. `raw` is core's documented request escape hatch. */
+export interface StoreReadContext {
+  orgId: string;
+  actor: { userId: string | null; [key: string]: unknown } | null;
+  raw: unknown;
+}
+
 export interface ChannelConnectorPluginOptions {
   connectors?: ChannelConnector[];
+  /**
+   * Confines store reads to a set the consumer chooses. See {@link ConfineStoreReads}.
+   *
+   * Absent by default, because narrowing an existing read for every deployment would be a breaking
+   * change to a published package. A consumer that needs confinement opts in; one that does not is
+   * unaffected.
+   */
+  confineStoreReads?: ConfineStoreReads;
   oauth?: { stateSecret: string; postConnectRedirect: string };
   inventoryTimeoutMs?: number;
   jobs?: JobsAdapter;
@@ -2266,11 +2295,24 @@ export class ChannelConnectorService {
     return Ok(redactStore(store));
   }
 
-  async listStores(orgId: string): Promise<PluginResult<PublicConnectedStore[]>> {
-    const rows = await this.db
-      .select()
-      .from(connectedStores)
-      .where(eq(connectedStores.organizationId, orgId));
+  async listStores(orgId: string, context?: StoreReadContext): Promise<PluginResult<PublicConnectedStore[]>> {
+    const allowed = this.options.confineStoreReads
+      ? await this.options.confineStoreReads(context ?? { orgId, actor: null, raw: undefined })
+      : null;
+    // An empty allow-list means the caller may read NOTHING, stated here rather than left to the
+    // query builder.
+    //
+    // MEASURED, because the first version of this comment claimed the guard was load-bearing and it
+    // is not: removing this line leaves every row in `confine-store-reads.test.ts` green, so drizzle
+    // already turns `inArray(id, [])` into a predicate that matches nothing. The guard is therefore
+    // the CONTRACT rather than the rescue — `[]` means none, whatever the builder does with an empty
+    // array on some future dialect or version. Worth keeping for that reason and not worth claiming
+    // more for: the row that covers this case is really watching drizzle, not this line.
+    if (allowed !== null && allowed.length === 0) return Ok([]);
+    const predicate = allowed === null
+      ? eq(connectedStores.organizationId, orgId)
+      : and(eq(connectedStores.organizationId, orgId), inArray(connectedStores.id, [...allowed]));
+    const rows = await this.db.select().from(connectedStores).where(predicate);
     return Ok((rows as ConnectedStore[]).map(redactStore));
   }