@porulle/plugin-channel-connector 0.66.0 → 0.68.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

@@ -365,10 +365,16 @@ export function channelConnectorPlugin(options = {}) {
                 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.` });
+                // Refused HERE, before the merchant reaches the provider: a grant issued for a shop retires
+                // that shop's other grants, so a refusal at the callback would already have broken them.
+                const claims = await service.connectClaims({ orgId, actor, raw, storeDomain });
+                if (!claims.ok)
+                    return connectOutcome(oauth.postConnectRedirect, { error: claims.code ?? "CONNECT_REFUSED", message: claims.error });
                 const state = signState({
                     provider,
                     orgId,
                     userId,
+                    claims: claims.value,
                     shopDomain: storeDomain,
                     exp: Math.floor(Date.now() / 1000) + 600,
                     jti: crypto.randomUUID(),
@@ -423,7 +429,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 +516,10 @@ 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 requested = input;
+                const normalize = service.getConnector(requested.provider)?.normalizeStoreDomain;
+                const claims = unwrap(await service.connectClaims({ orgId, actor, raw, storeDomain: (normalize ? normalize(requested.storeDomain) : undefined) ?? requested.storeDomain }));
+                return unwrap(await service.connectStore(orgId, input, { orgId, userId: actor?.userId ?? null, claims, raw }));
             });
             channels.get("/stores")
                 .summary("List connected channel stores")

package/dist/live-credentials.d.ts

@@ -15,10 +15,15 @@ import type { ChannelConnector, ChannelConnectorError, ChannelStore, PluginDb, R
  * 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>>;
+export declare function resolveLiveCredentials(connector: ChannelConnector, db: PluginDb, store: ChannelStore, options?: {
+    force?: boolean;
+}): 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.
+ *
+ * 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.
  */
 export declare function withLiveCredentials(connector: ChannelConnector, db: PluginDb): ChannelConnector;

package/dist/live-credentials.js

@@ -1,4 +1,4 @@
-import { Err, Ok } from "@porulle/core";
+import { CHANNEL_CREDENTIALS_REJECTED, Err, Ok } from "@porulle/core";
 import { and, eq, sql } from "@porulle/core/drizzle";
 import { connectedStores } from "./schema.js";
 /**
@@ -17,10 +17,10 @@ import { connectedStores } from "./schema.js";
  * 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) {
+export async function resolveLiveCredentials(connector, db, store, options = {}) {
     if (!connector.liveCredentials)
         return Ok(store);
-    const answer = await connector.liveCredentials(store);
+    const answer = await connector.liveCredentials(store, options);
     if (!answer.ok) {
         if (answer.error.retriable !== true) {
             await db.update(connectedStores).set({ status: "error", updatedAt: new Date() }).where(eq(connectedStores.id, store.id));
@@ -44,6 +44,9 @@ export async function resolveLiveCredentials(connector, db, 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.
+ *
+ * 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.
  */
 export function withLiveCredentials(connector, db) {
     if (!connector.liveCredentials)
@@ -52,7 +55,13 @@ export function withLiveCredentials(connector, db) {
         const current = await resolveLiveCredentials(connector, db, store);
         if (!current.ok)
             return current;
-        return call.call(connector, current.value, ...args);
+        const first = await call.call(connector, current.value, ...args);
+        if (first.ok || first.error.code !== CHANNEL_CREDENTIALS_REJECTED)
+            return first;
+        const refreshed = await resolveLiveCredentials(connector, db, current.value, { force: true });
+        if (!refreshed.ok)
+            return refreshed;
+        return call.call(connector, refreshed.value, ...args);
     };
     return {
         ...connector,

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,25 @@ 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 — before the merchant is sent to the provider, which matters: a
+ * provider such as Shopify retires a shop's other grants the moment a new one is issued, so a
+ * connection refused only at the callback has already broken the shop's existing one. `storeDomain` is
+ * the store being connected, canonicalised. Runs for OAuth start and for `POST /stores`.
+ */
+export type ConnectClaims = (context: StoreReadContext & {
+    storeDomain: string;
+}) => 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 +143,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 +171,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 +514,10 @@ 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 & {
+        storeDomain: string;
+    }): 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

@@ -1299,6 +1299,16 @@ export class ChannelConnectorService {
                 continue;
             }
             variantIds.set(sourceVariant.externalId, variantId);
+            // The provider's per-variant facts (the inventory item a stock webhook names, the weight shipping
+            // prices by) merge into the variant per key, as entity metadata does: the source's keys overwrite
+            // their own and nothing else. The import fast path writes them at creation; without this the
+            // editor path — every reconcile — left them off, and a stock webhook could not find its variant.
+            const sourceMetadata = sourceVariant.metadata ?? {};
+            if (Object.keys(sourceMetadata).length > 0) {
+                await this.db.update(variants)
+                    .set({ metadata: sql `coalesce(${variants.metadata}, '{}'::jsonb) || ${JSON.stringify(sourceMetadata)}::jsonb` })
+                    .where(and(eq(variants.id, variantId), sql `not (coalesce(${variants.metadata}, '{}'::jsonb) @> ${JSON.stringify(sourceMetadata)}::jsonb)`));
+            }
             if (applyOptionValues) {
                 const desiredOptionValueIds = Object.entries(sourceVariant.optionValues ?? {})
                     .map(([name, value]) => optionValueIds.get(name)?.get(value))
@@ -2269,7 +2279,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 +2298,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;
@@ -3465,14 +3486,21 @@ export class ChannelConnectorService {
                 archived += 1;
             }
         }
-        const inventory = await connector.fetchInventory(store, mappings.map((mapping) => mapping.externalId));
+        // Stock is levelled against the mappings as they stand AFTER convergence. Read before it, as the
+        // archive plan above must be, a first import walked an empty list and left every product it had
+        // just created with no inventory level at all. Re-read only when convergence wrote something: an
+        // unchanged reconcile creates no mapping and keeps its statement budget.
+        const levelled = converged.value.imported + converged.value.converged > 0
+            ? await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId)))
+            : mappings;
+        const inventory = await connector.fetchInventory(store, levelled.map((mapping) => mapping.externalId));
         if (!inventory.ok)
             return PluginErr(inventory.error.message);
         const existingLevels = await this.db.select().from(inventoryLevels).where(eq(inventoryLevels.organizationId, orgId));
         const inventoryService = this.services.inventory;
         let inventoryUpdated = 0;
         for (const level of inventory.value) {
-            const mapping = mappings.find((entry) => entry.externalId === level.externalId);
+            const mapping = levelled.find((entry) => entry.externalId === level.externalId);
             if (!mapping)
                 continue;
             const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@porulle/plugin-channel-connector",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -22,15 +22,15 @@
   "dependencies": {
     "@hono/zod-openapi": "^1.2.2",
     "hono": "^4.12.5",
-    "@porulle/core": "0.66.0"
+    "@porulle/core": "0.68.0"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/eslint-config": "0.1.0",
-    "@porulle/typescript-config": "0.1.0"
+    "@porulle/typescript-config": "0.1.0",
+    "@porulle/eslint-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -238,6 +238,7 @@ export type {
   ChannelComplianceData,
   ChannelConnectorPluginOptions,
   ConfineStores,
+  ConnectClaims,
   OnStoreCatalogChanged,
   StoreConnectActor,
   StoreReadContext,
@@ -534,10 +535,15 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
           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.` });
+          // Refused HERE, before the merchant reaches the provider: a grant issued for a shop retires
+          // that shop's other grants, so a refusal at the callback would already have broken them.
+          const claims = await service.connectClaims({ orgId, actor, raw, storeDomain });
+          if (!claims.ok) return connectOutcome(oauth.postConnectRedirect, { error: claims.code ?? "CONNECT_REFUSED", message: claims.error });
           const state = signState({
             provider,
             orgId,
             userId,
+            claims: claims.value,
             shopDomain: storeDomain,
             exp: Math.floor(Date.now() / 1000) + 600,
             jti: crypto.randomUUID(),
@@ -583,7 +589,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 +671,9 @@ export function channelConnectorPlugin(options: ChannelConnectorPluginOptions =
           webhookSecret: z.string().min(1).optional(),
         }))
         .handler(async ({ input, orgId, actor, raw }: ChannelRouteContext) => {
+          const requested = input as { provider: string; storeDomain: string };
+          const normalize = service.getConnector(requested.provider)?.normalizeStoreDomain;
+          const claims = unwrap(await service.connectClaims({ orgId, actor, raw, storeDomain: (normalize ? normalize(requested.storeDomain) : undefined) ?? requested.storeDomain }));
           return unwrap(await service.connectStore(
             orgId,
             input as {
@@ -673,7 +682,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/live-credentials.ts

@@ -1,4 +1,4 @@
-import { Err, Ok } from "@porulle/core";
+import { CHANNEL_CREDENTIALS_REJECTED, Err, Ok } from "@porulle/core";
 import type { ChannelConnector, ChannelConnectorError, ChannelStore, PluginDb, Result } from "@porulle/core";
 import { and, eq, sql } from "@porulle/core/drizzle";
 import { connectedStores } from "./schema.js";
@@ -19,9 +19,9 @@ import { connectedStores } from "./schema.js";
  * 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: ChannelConnector, db: PluginDb, store: ChannelStore): Promise<Result<ChannelStore, ChannelConnectorError>> {
+export async function resolveLiveCredentials(connector: ChannelConnector, db: PluginDb, store: ChannelStore, options: { force?: boolean } = {}): Promise<Result<ChannelStore, ChannelConnectorError>> {
   if (!connector.liveCredentials) return Ok(store);
-  const answer = await connector.liveCredentials(store);
+  const answer = await connector.liveCredentials(store, options);
   if (!answer.ok) {
     if (answer.error.retriable !== true) {
       await db.update(connectedStores).set({ status: "error", updatedAt: new Date() }).where(eq(connectedStores.id, store.id));
@@ -45,13 +45,20 @@ type StoreCall<A extends unknown[], T> = (store: ChannelStore, ...args: A) => Pr
  * 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.
+ *
+ * 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.
  */
 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;
-    return call.call(connector, current.value, ...args);
+    const first = await call.call(connector, current.value, ...args);
+    if (first.ok || first.error.code !== CHANNEL_CREDENTIALS_REJECTED) return first;
+    const refreshed = await resolveLiveCredentials(connector, db, current.value, { force: true });
+    if (!refreshed.ok) return refreshed;
+    return call.call(connector, refreshed.value, ...args);
   };
   return {
     ...connector,

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,25 @@ 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 — before the merchant is sent to the provider, which matters: a
+ * provider such as Shopify retires a shop's other grants the moment a new one is issued, so a
+ * connection refused only at the callback has already broken the shop's existing one. `storeDomain` is
+ * the store being connected, canonicalised. Runs for OAuth start and for `POST /stores`.
+ */
+export type ConnectClaims = (context: StoreReadContext & { storeDomain: string }) => 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 +281,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 +303,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}. */
@@ -2043,6 +2060,16 @@ export class ChannelConnectorService {
         continue;
       }
       variantIds.set(sourceVariant.externalId, variantId);
+      // The provider's per-variant facts (the inventory item a stock webhook names, the weight shipping
+      // prices by) merge into the variant per key, as entity metadata does: the source's keys overwrite
+      // their own and nothing else. The import fast path writes them at creation; without this the
+      // editor path — every reconcile — left them off, and a stock webhook could not find its variant.
+      const sourceMetadata = sourceVariant.metadata ?? {};
+      if (Object.keys(sourceMetadata).length > 0) {
+        await this.db.update(variants)
+          .set({ metadata: sql`coalesce(${variants.metadata}, '{}'::jsonb) || ${JSON.stringify(sourceMetadata)}::jsonb` })
+          .where(and(eq(variants.id, variantId), sql`not (coalesce(${variants.metadata}, '{}'::jsonb) @> ${JSON.stringify(sourceMetadata)}::jsonb)`));
+      }
       if (applyOptionValues) {
         const desiredOptionValueIds = Object.entries(sourceVariant.optionValues ?? {})
           .map(([name, value]) => optionValueIds.get(name)?.get(value))
@@ -3165,7 +3192,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 +3210,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 & { storeDomain: string }): 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;
@@ -4522,7 +4559,14 @@ export class ChannelConnectorService {
       }
     }
 
-    const inventory = await connector.fetchInventory(store as ChannelStore, mappings.map((mapping) => mapping.externalId));
+    // Stock is levelled against the mappings as they stand AFTER convergence. Read before it, as the
+    // archive plan above must be, a first import walked an empty list and left every product it had
+    // just created with no inventory level at all. Re-read only when convergence wrote something: an
+    // unchanged reconcile creates no mapping and keeps its statement budget.
+    const levelled = converged.value.imported + converged.value.converged > 0
+      ? await this.db.select().from(channelEntityMap).where(and(eq(channelEntityMap.organizationId, orgId), eq(channelEntityMap.storeId, storeId)))
+      : mappings;
+    const inventory = await connector.fetchInventory(store as ChannelStore, levelled.map((mapping) => mapping.externalId));
     if (!inventory.ok) return PluginErr(inventory.error.message);
     const existingLevels = await this.db.select().from(inventoryLevels).where(eq(inventoryLevels.organizationId, orgId));
     const inventoryService = this.services.inventory as {
@@ -4530,7 +4574,7 @@ export class ChannelConnectorService {
     };
     let inventoryUpdated = 0;
     for (const level of inventory.value) {
-      const mapping = mappings.find((entry) => entry.externalId === level.externalId);
+      const mapping = levelled.find((entry) => entry.externalId === level.externalId);
       if (!mapping) continue;
       const current = existingLevels.find((entry) => entry.entityId === mapping.entityId && entry.variantId === (mapping.variantId ?? null));
       // Stock cannot sit below zero here, so negative remote stock compares as the zero it is stored as.