@thorprovider/adapters 3.0.2

package/src/metadata/channel-scope-validation.ts

@@ -0,0 +1,151 @@
+/**
+ * Channel Scope Validation — Pure TypeScript (no external deps)
+ *
+ * Validates channel-scope metadata before it is written to the backend.
+ * Keeps all validation logic in L2 so that L5 starters don't duplicate checks.
+ *
+ * @module metadata/channel-scope-validation
+ */
+
+import type { ChannelScopeMetadata, ChannelScopeable } from './channel-scope';
+import { CHANNEL_SCOPE_KEY } from './channel-scope';
+
+// ────────────────────────────────────────────────────────────────────
+// Errors
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Thrown when channel-scope validation fails.
+ *
+ * Consumers can catch this specific type to provide user-friendly feedback
+ * without leaking internal details.
+ */
+export class ChannelScopeValidationError extends Error {
+  public readonly field: string;
+  public readonly value: unknown;
+
+  constructor(message: string, field: string, value?: unknown) {
+    super(message);
+    this.name = 'ChannelScopeValidationError';
+    this.field = field;
+    this.value = value;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Validation functions
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Validate that a channel ID is a non-empty string.
+ *
+ * Does **not** enforce a specific prefix (e.g. `"sc_"`) because different
+ * backends use different conventions:
+ * - Medusa: `"sc_01HXXX"`
+ * - Shopify: `"gid://shopify/Channel/789"`
+ * - WooCommerce: `"1"` (numeric string)
+ *
+ * @throws {ChannelScopeValidationError}
+ */
+export function validateChannelId(channelId: unknown): asserts channelId is string {
+  if (typeof channelId !== 'string' || channelId.trim().length === 0) {
+    throw new ChannelScopeValidationError(
+      'Channel ID must be a non-empty string',
+      'channelId',
+      channelId,
+    );
+  }
+
+  // Sanity upper-bound for ID length (guards against payload abuse)
+  if (channelId.length > 256) {
+    throw new ChannelScopeValidationError(
+      'Channel ID exceeds maximum length (256)',
+      'channelId',
+      channelId,
+    );
+  }
+}
+
+/**
+ * Validate that an entity ID is a non-empty string.
+ *
+ * @throws {ChannelScopeValidationError}
+ */
+export function validateEntityId(entityId: unknown, label = 'entityId'): asserts entityId is string {
+  if (typeof entityId !== 'string' || entityId.trim().length === 0) {
+    throw new ChannelScopeValidationError(
+      `${label} must be a non-empty string`,
+      label,
+      entityId,
+    );
+  }
+}
+
+/**
+ * Validate that the `assignedBy` value (if provided) is a reasonable string.
+ *
+ * @throws {ChannelScopeValidationError}
+ */
+export function validateAssignedBy(assignedBy: unknown): asserts assignedBy is string | undefined {
+  if (assignedBy === undefined || assignedBy === null) return;
+  if (typeof assignedBy !== 'string') {
+    throw new ChannelScopeValidationError(
+      'assignedBy must be a string',
+      'assignedBy',
+      assignedBy,
+    );
+  }
+  if (assignedBy.length > 512) {
+    throw new ChannelScopeValidationError(
+      'assignedBy exceeds maximum length (512)',
+      'assignedBy',
+      assignedBy,
+    );
+  }
+}
+
+/**
+ * Full validation for a channel-scope assignment operation.
+ *
+ * Call before writing channel scope metadata to any entity.
+ *
+ * @throws {ChannelScopeValidationError} with descriptive field + value
+ *
+ * @example
+ * ```typescript
+ * validateChannelScopeAssignment('cus_123', 'sc_01HXXX', 'admin@store.com');
+ * // If no error, safe to proceed
+ * ```
+ */
+export function validateChannelScopeAssignment(
+  entityId: string,
+  channelId: string,
+  assignedBy?: string,
+): void {
+  validateEntityId(entityId, 'entityId');
+  validateChannelId(channelId);
+  validateAssignedBy(assignedBy);
+}
+
+/**
+ * Validate that an entity is currently scoped to the expected channel.
+ *
+ * Useful as a guard before performing operations that should only
+ * affect entities within the caller's channel (e.g. a dropshipper editing
+ * a customer that must belong to their channel).
+ *
+ * @throws {ChannelScopeValidationError} if entity does not belong to expectedChannelId
+ */
+export function assertEntityBelongsToChannel(
+  entity: ChannelScopeable,
+  expectedChannelId: string,
+): void {
+  const actual = entity.metadata?.[CHANNEL_SCOPE_KEY];
+  if (actual !== expectedChannelId) {
+    throw new ChannelScopeValidationError(
+      `Entity "${entity.id}" does not belong to channel "${expectedChannelId}" (actual: "${actual ?? 'none'}")`,
+      CHANNEL_SCOPE_KEY,
+      actual,
+    );
+  }
+}

package/src/metadata/channel-scope.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * Channel Scope — Backend-Agnostic Multi-Tenant Helpers
+ *
+ * Provides utilities for tagging, reading and filtering entity metadata by
+ * sales-channel (or any future tenant key). Works with any backend that
+ * exposes a writable `metadata: Record<string, unknown>` field on its
+ * entities (Medusa, Shopify metafields, WooCommerce meta, etc.).
+ *
+ * ## Design decisions
+ *
+ * | Decision | Rationale |
+ * |----------|-----------|
+ * | Flat key (`sales_channel_id`) | Simpler queries, no prefix parsing required |
+ * | Metadata, not custom fields | Zero DB migrations; works across backends |
+ * | Pure functions | No side effects → easily testable; usable in any layer |
+ * | `assigned_at` timestamp | Audit trail for dropshipper / admin assignment |
+ *
+ * @module metadata/channel-scope
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHANNEL_ASSIGNED_BY_KEY = exports.CHANNEL_ASSIGNED_AT_KEY = exports.CHANNEL_SCOPE_KEY = void 0;
+exports.buildChannelScopeMetadata = buildChannelScopeMetadata;
+exports.getChannelScope = getChannelScope;
+exports.isScopedToChannel = isScopedToChannel;
+exports.isGlobalEntity = isGlobalEntity;
+exports.filterByChannel = filterByChannel;
+exports.filterGlobalOnly = filterGlobalOnly;
+exports.partitionByChannel = partitionByChannel;
+// ────────────────────────────────────────────────────────────────────
+// Constants
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Well-known metadata key used to store the owning sales-channel on any
+ * entity that Medusa (or the backend) does not natively scope.
+ *
+ * Convention: every entity whose metadata contains this key is
+ * considered "owned" by the referenced channel. Entities without it
+ * are global / unscoped.
+ */
+exports.CHANNEL_SCOPE_KEY = 'sales_channel_id';
+/**
+ * Optional audit key — ISO-8601 timestamp of when the channel was assigned.
+ */
+exports.CHANNEL_ASSIGNED_AT_KEY = 'channel_assigned_at';
+/**
+ * Optional audit key — who assigned the entity to the channel.
+ * Value is a free-form string (admin email, user id, "system", etc.).
+ */
+exports.CHANNEL_ASSIGNED_BY_KEY = 'channel_assigned_by';
+// ────────────────────────────────────────────────────────────────────
+// Builders
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Build channel-scope metadata payload.
+ *
+ * The returned object should be **merged** into the entity's existing
+ * `metadata` field when calling `updateCustomer`, `updateOrder`, etc.
+ *
+ * @param channelId  - Sales-channel ID (e.g. `"sc_01HXXX"`)
+ * @param assignedBy - Optional identifier of who performed the assignment
+ * @returns Metadata fragment ready to spread into an update payload
+ *
+ * @example
+ * ```typescript
+ * const scope = buildChannelScopeMetadata('sc_01HXXX', 'admin@store.com');
+ * await commerce.updateCustomer(customerId, {
+ *   metadata: { ...existingMeta, ...scope },
+ * });
+ * ```
+ */
+function buildChannelScopeMetadata(channelId, assignedBy) {
+    var _a;
+    var payload = (_a = {},
+        _a[exports.CHANNEL_SCOPE_KEY] = channelId,
+        _a[exports.CHANNEL_ASSIGNED_AT_KEY] = new Date().toISOString(),
+        _a);
+    if (assignedBy) {
+        payload[exports.CHANNEL_ASSIGNED_BY_KEY] = assignedBy;
+    }
+    return payload;
+}
+// ────────────────────────────────────────────────────────────────────
+// Readers
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Read the channel-scope value from an entity's metadata.
+ *
+ * @returns The channel ID string, or `null` if the entity has no scope set.
+ */
+function getChannelScope(entity) {
+    var _a;
+    var value = (_a = entity.metadata) === null || _a === void 0 ? void 0 : _a[exports.CHANNEL_SCOPE_KEY];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * Check if an entity is scoped to a specific channel.
+ *
+ * @param entity    - Any entity with optional `metadata`
+ * @param channelId - Channel ID to match against
+ * @returns `true` if entity's metadata contains a matching scope key
+ */
+function isScopedToChannel(entity, channelId) {
+    return getChannelScope(entity) === channelId;
+}
+/**
+ * Check if an entity has **no** channel scope (i.e. it is "global").
+ */
+function isGlobalEntity(entity) {
+    return getChannelScope(entity) === null;
+}
+// ────────────────────────────────────────────────────────────────────
+// Filters
+// ────────────────────────────────────────────────────────────────────
+/**
+ * Filter an array of entities to only those belonging to a channel.
+ *
+ * If `channelId` is `undefined` or empty, returns the full array unfiltered.
+ * This preserves backward compatibility for admin views that intentionally
+ * list all entities regardless of tenant.
+ *
+ * @param entities  - Array of channel-scopeable entities
+ * @param channelId - Optional channel ID to filter by
+ * @returns Filtered (or unfiltered) array
+ *
+ * @example
+ * ```typescript
+ * const allCustomers = await commerce.getCustomers();
+ * const myCustomers = filterByChannel(allCustomers, salesChannelId);
+ * ```
+ */
+function filterByChannel(entities, channelId) {
+    if (!channelId)
+        return entities;
+    return entities.filter(function (e) { return isScopedToChannel(e, channelId); });
+}
+/**
+ * Filter an array of entities to only those that are global (unscoped).
+ *
+ * Useful for admin views that want to list entities not yet assigned to
+ * any channel.
+ */
+function filterGlobalOnly(entities) {
+    return entities.filter(isGlobalEntity);
+}
+/**
+ * Partition entities into `{ scoped, global }` groups.
+ *
+ * @param entities  - Array of channel-scopeable entities
+ * @param channelId - Channel ID to partition against
+ * @returns Object with `scoped` (matching channel) and `global` (no scope) arrays
+ *
+ * @example
+ * ```typescript
+ * const { scoped, global } = partitionByChannel(customers, 'sc_123');
+ * // scoped → customers assigned to sc_123
+ * // global → customers not assigned to any channel
+ * ```
+ */
+function partitionByChannel(entities, channelId) {
+    var scoped = [];
+    var global = [];
+    for (var _i = 0, entities_1 = entities; _i < entities_1.length; _i++) {
+        var entity = entities_1[_i];
+        if (isScopedToChannel(entity, channelId)) {
+            scoped.push(entity);
+        }
+        else if (isGlobalEntity(entity)) {
+            global.push(entity);
+        }
+        // Entities scoped to a *different* channel are silently excluded.
+    }
+    return { scoped: scoped, global: global };
+}

package/src/metadata/channel-scope.ts

@@ -0,0 +1,215 @@
+/**
+ * Channel Scope — Backend-Agnostic Multi-Tenant Helpers
+ *
+ * Provides utilities for tagging, reading and filtering entity metadata by
+ * sales-channel (or any future tenant key). Works with any backend that
+ * exposes a writable `metadata: Record<string, unknown>` field on its
+ * entities (Medusa, Shopify metafields, WooCommerce meta, etc.).
+ *
+ * ## Design decisions
+ *
+ * | Decision | Rationale |
+ * |----------|-----------|
+ * | Flat key (`sales_channel_id`) | Simpler queries, no prefix parsing required |
+ * | Metadata, not custom fields | Zero DB migrations; works across backends |
+ * | Pure functions | No side effects → easily testable; usable in any layer |
+ * | `assigned_at` timestamp | Audit trail for dropshipper / admin assignment |
+ *
+ * @module metadata/channel-scope
+ */
+
+// ────────────────────────────────────────────────────────────────────
+// Constants
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Well-known metadata key used to store the owning sales-channel on any
+ * entity that Medusa (or the backend) does not natively scope.
+ *
+ * Convention: every entity whose metadata contains this key is
+ * considered "owned" by the referenced channel. Entities without it
+ * are global / unscoped.
+ */
+export const CHANNEL_SCOPE_KEY = 'sales_channel_id' as const;
+
+/**
+ * Optional audit key — ISO-8601 timestamp of when the channel was assigned.
+ */
+export const CHANNEL_ASSIGNED_AT_KEY = 'channel_assigned_at' as const;
+
+/**
+ * Optional audit key — who assigned the entity to the channel.
+ * Value is a free-form string (admin email, user id, "system", etc.).
+ */
+export const CHANNEL_ASSIGNED_BY_KEY = 'channel_assigned_by' as const;
+
+// ────────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Minimal shape any entity must satisfy in order to participate in
+ * channel-scope filtering.  Compatible with @thorprovider/types Customer,
+ * Order, ProductCategory, etc.
+ */
+export interface ChannelScopeable {
+  id: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Payload produced by `buildChannelScopeMetadata()`.
+ * Can be spread directly into an `updateCustomer` / `updateOrder` call.
+ */
+export interface ChannelScopeMetadata {
+  [CHANNEL_SCOPE_KEY]: string;
+  [CHANNEL_ASSIGNED_AT_KEY]: string;
+  [CHANNEL_ASSIGNED_BY_KEY]?: string;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Builders
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Build channel-scope metadata payload.
+ *
+ * The returned object should be **merged** into the entity's existing
+ * `metadata` field when calling `updateCustomer`, `updateOrder`, etc.
+ *
+ * @param channelId  - Sales-channel ID (e.g. `"sc_01HXXX"`)
+ * @param assignedBy - Optional identifier of who performed the assignment
+ * @returns Metadata fragment ready to spread into an update payload
+ *
+ * @example
+ * ```typescript
+ * const scope = buildChannelScopeMetadata('sc_01HXXX', 'admin@store.com');
+ * await commerce.updateCustomer(customerId, {
+ *   metadata: { ...existingMeta, ...scope },
+ * });
+ * ```
+ */
+export function buildChannelScopeMetadata(
+  channelId: string,
+  assignedBy?: string,
+): ChannelScopeMetadata {
+  const payload: ChannelScopeMetadata = {
+    [CHANNEL_SCOPE_KEY]: channelId,
+    [CHANNEL_ASSIGNED_AT_KEY]: new Date().toISOString(),
+  };
+
+  if (assignedBy) {
+    payload[CHANNEL_ASSIGNED_BY_KEY] = assignedBy;
+  }
+
+  return payload;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Readers
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Read the channel-scope value from an entity's metadata.
+ *
+ * @returns The channel ID string, or `null` if the entity has no scope set.
+ */
+export function getChannelScope(entity: ChannelScopeable): string | null {
+  const value = entity.metadata?.[CHANNEL_SCOPE_KEY];
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+/**
+ * Check if an entity is scoped to a specific channel.
+ *
+ * @param entity    - Any entity with optional `metadata`
+ * @param channelId - Channel ID to match against
+ * @returns `true` if entity's metadata contains a matching scope key
+ */
+export function isScopedToChannel(
+  entity: ChannelScopeable,
+  channelId: string,
+): boolean {
+  return getChannelScope(entity) === channelId;
+}
+
+/**
+ * Check if an entity has **no** channel scope (i.e. it is "global").
+ */
+export function isGlobalEntity(entity: ChannelScopeable): boolean {
+  return getChannelScope(entity) === null;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Filters
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Filter an array of entities to only those belonging to a channel.
+ *
+ * If `channelId` is `undefined` or empty, returns the full array unfiltered.
+ * This preserves backward compatibility for admin views that intentionally
+ * list all entities regardless of tenant.
+ *
+ * @param entities  - Array of channel-scopeable entities
+ * @param channelId - Optional channel ID to filter by
+ * @returns Filtered (or unfiltered) array
+ *
+ * @example
+ * ```typescript
+ * const allCustomers = await commerce.getCustomers();
+ * const myCustomers = filterByChannel(allCustomers, salesChannelId);
+ * ```
+ */
+export function filterByChannel<T extends ChannelScopeable>(
+  entities: T[],
+  channelId?: string,
+): T[] {
+  if (!channelId) return entities;
+  return entities.filter((e) => isScopedToChannel(e, channelId));
+}
+
+/**
+ * Filter an array of entities to only those that are global (unscoped).
+ *
+ * Useful for admin views that want to list entities not yet assigned to
+ * any channel.
+ */
+export function filterGlobalOnly<T extends ChannelScopeable>(
+  entities: T[],
+): T[] {
+  return entities.filter(isGlobalEntity);
+}
+
+/**
+ * Partition entities into `{ scoped, global }` groups.
+ *
+ * @param entities  - Array of channel-scopeable entities
+ * @param channelId - Channel ID to partition against
+ * @returns Object with `scoped` (matching channel) and `global` (no scope) arrays
+ *
+ * @example
+ * ```typescript
+ * const { scoped, global } = partitionByChannel(customers, 'sc_123');
+ * // scoped → customers assigned to sc_123
+ * // global → customers not assigned to any channel
+ * ```
+ */
+export function partitionByChannel<T extends ChannelScopeable>(
+  entities: T[],
+  channelId: string,
+): { scoped: T[]; global: T[] } {
+  const scoped: T[] = [];
+  const global: T[] = [];
+
+  for (const entity of entities) {
+    if (isScopedToChannel(entity, channelId)) {
+      scoped.push(entity);
+    } else if (isGlobalEntity(entity)) {
+      global.push(entity);
+    }
+    // Entities scoped to a *different* channel are silently excluded.
+  }
+
+  return { scoped, global };
+}

package/src/metadata/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Metadata — Channel Scope Utilities
+ *
+ * Backend-agnostic helpers for multi-tenant channel scoping.
+ * Used by L2 adapters to tag, validate and filter entities by sales channel.
+ *
+ * @module metadata
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertEntityBelongsToChannel = exports.validateChannelScopeAssignment = exports.validateAssignedBy = exports.validateEntityId = exports.validateChannelId = exports.ChannelScopeValidationError = exports.partitionByChannel = exports.filterGlobalOnly = exports.filterByChannel = exports.isGlobalEntity = exports.isScopedToChannel = exports.getChannelScope = exports.buildChannelScopeMetadata = exports.CHANNEL_ASSIGNED_BY_KEY = exports.CHANNEL_ASSIGNED_AT_KEY = exports.CHANNEL_SCOPE_KEY = void 0;
+// Builders, readers & filters
+var channel_scope_1 = require("./channel-scope");
+Object.defineProperty(exports, "CHANNEL_SCOPE_KEY", { enumerable: true, get: function () { return channel_scope_1.CHANNEL_SCOPE_KEY; } });
+Object.defineProperty(exports, "CHANNEL_ASSIGNED_AT_KEY", { enumerable: true, get: function () { return channel_scope_1.CHANNEL_ASSIGNED_AT_KEY; } });
+Object.defineProperty(exports, "CHANNEL_ASSIGNED_BY_KEY", { enumerable: true, get: function () { return channel_scope_1.CHANNEL_ASSIGNED_BY_KEY; } });
+Object.defineProperty(exports, "buildChannelScopeMetadata", { enumerable: true, get: function () { return channel_scope_1.buildChannelScopeMetadata; } });
+Object.defineProperty(exports, "getChannelScope", { enumerable: true, get: function () { return channel_scope_1.getChannelScope; } });
+Object.defineProperty(exports, "isScopedToChannel", { enumerable: true, get: function () { return channel_scope_1.isScopedToChannel; } });
+Object.defineProperty(exports, "isGlobalEntity", { enumerable: true, get: function () { return channel_scope_1.isGlobalEntity; } });
+Object.defineProperty(exports, "filterByChannel", { enumerable: true, get: function () { return channel_scope_1.filterByChannel; } });
+Object.defineProperty(exports, "filterGlobalOnly", { enumerable: true, get: function () { return channel_scope_1.filterGlobalOnly; } });
+Object.defineProperty(exports, "partitionByChannel", { enumerable: true, get: function () { return channel_scope_1.partitionByChannel; } });
+// Validation
+var channel_scope_validation_1 = require("./channel-scope-validation");
+Object.defineProperty(exports, "ChannelScopeValidationError", { enumerable: true, get: function () { return channel_scope_validation_1.ChannelScopeValidationError; } });
+Object.defineProperty(exports, "validateChannelId", { enumerable: true, get: function () { return channel_scope_validation_1.validateChannelId; } });
+Object.defineProperty(exports, "validateEntityId", { enumerable: true, get: function () { return channel_scope_validation_1.validateEntityId; } });
+Object.defineProperty(exports, "validateAssignedBy", { enumerable: true, get: function () { return channel_scope_validation_1.validateAssignedBy; } });
+Object.defineProperty(exports, "validateChannelScopeAssignment", { enumerable: true, get: function () { return channel_scope_validation_1.validateChannelScopeAssignment; } });
+Object.defineProperty(exports, "assertEntityBelongsToChannel", { enumerable: true, get: function () { return channel_scope_validation_1.assertEntityBelongsToChannel; } });

package/src/metadata/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Metadata — Channel Scope Utilities
+ *
+ * Backend-agnostic helpers for multi-tenant channel scoping.
+ * Used by L2 adapters to tag, validate and filter entities by sales channel.
+ *
+ * @module metadata
+ */
+
+// Builders, readers & filters
+export {
+  CHANNEL_SCOPE_KEY,
+  CHANNEL_ASSIGNED_AT_KEY,
+  CHANNEL_ASSIGNED_BY_KEY,
+  buildChannelScopeMetadata,
+  getChannelScope,
+  isScopedToChannel,
+  isGlobalEntity,
+  filterByChannel,
+  filterGlobalOnly,
+  partitionByChannel,
+} from './channel-scope';
+
+export type {
+  ChannelScopeable,
+  ChannelScopeMetadata,
+} from './channel-scope';
+
+// Validation
+export {
+  ChannelScopeValidationError,
+  validateChannelId,
+  validateEntityId,
+  validateAssignedBy,
+  validateChannelScopeAssignment,
+  assertEntityBelongsToChannel,
+} from './channel-scope-validation';

package/src/providers/bigcommerce/bigcommerce.ts

@@ -0,0 +1,6 @@
+/**
+ * @thorprovider/adapters — BigCommerce Provider exports
+ */
+export { BigCommerceProvider } from './index';
+export type { BigCommerceProviderConfig } from './index';
+export * from './transforms';