@thorprovider/adapters 4.2.1 → 5.0.0

package/src/metadata/channel-scope.js

@@ -1,174 +0,0 @@
-"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/index.js

@@ -1,31 +0,0 @@
-"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/providers/bigcommerce/bigcommerce.ts

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

package/src/providers/bigcommerce/index.ts

@@ -1,315 +0,0 @@
-/**
- * @thorprovider/adapters — BigCommerce Provider
- * Implements CommerceProvider for BigCommerce REST Storefront API
- *
- * Uses raw fetch against BigCommerce Storefront REST API.
- * The official `@bigcommerce/storefront-data-hooks` is deprecated (3 years unmaintained).
- */
-
-import type {
-  Product,
-  GetProductsOptions,
-  Cart,
-  CartLineInput,
-  CartLineUpdate,
-  Collection,
-  CollectionProductsOptions,
-  GetCollectionsOptions,
-  ProductCategory,
-  GetCategoriesOptions,
-  Order,
-  GetOrdersOptions,
-  Customer,
-  Address,
-  PaymentMethod,
-  PaymentMethodsOptions,
-  ShippingMethod,
-  StockLocation,
-  InventoryLevel,
-  StockValidation,
-  FulfillmentOption,
-  StorefrontContext,
-  BackendCapabilities,
-} from '@thorprovider/types';
-import type { CommerceProvider, ProviderConfig } from '../../types/provider';
-import { BIGCOMMERCE_CAPABILITIES } from '../../types/capabilities.types';
-import { createLogger } from '../../core/logger';
-import { ProviderAPIError } from '../../core/errors';
-import {
-  transformProduct,
-  transformCart,
-  transformCollection,
-  transformCustomer,
-  transformOrder,
-} from './transforms';
-
-/**
- * BigCommerce provider configuration
- */
-export interface BigCommerceProviderConfig extends ProviderConfig {
-  /** BigCommerce store hash */
-  storeHash: string;
-  /** Storefront API token (JWT) */
-  storefrontApiToken: string;
-  /** Storefront API URL (usually https://store-{hash}.mybigcommerce.com) */
-  storefrontApiUrl: string;
-  /** Channel ID */
-  channelId: string;
-  /** Default currency code (default: 'USD') */
-  currencyCode?: string;
-}
-
-export class BigCommerceProvider implements CommerceProvider {
-  readonly name = 'bigcommerce';
-  readonly version = '1.0.0';
-  readonly capabilities: BackendCapabilities = BIGCOMMERCE_CAPABILITIES;
-
-  private logger: ReturnType<typeof createLogger>;
-  private storefrontApiUrl: string;
-  private storeHash: string;
-  private channelId: string;
-  private currencyCode: string;
-  private headers: Record<string, string>;
-
-  constructor(config: BigCommerceProviderConfig) {
-    this.logger = createLogger('BigCommerceProvider', config.debug);
-    this.storefrontApiUrl = config.storefrontApiUrl.replace(/\/$/, '');
-    this.storeHash = config.storeHash;
-    this.channelId = config.channelId;
-    this.currencyCode = config.currencyCode ?? 'USD';
-    this.headers = {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${config.storefrontApiToken}`,
-    };
-    this.logger.info('Initializing BigCommerce Provider', { storeHash: this.storeHash, channelId: this.channelId });
-  }
-
-  private async fetchApi<T = any>(path: string, init?: RequestInit): Promise<T> {
-    const url = `${this.storefrontApiUrl}${path}`;
-    const response = await fetch(url, {
-      ...init,
-      headers: { ...this.headers, ...init?.headers },
-    });
-
-    if (!response.ok) {
-      throw new ProviderAPIError(
-        `BigCommerce API error: ${response.status} ${response.statusText}`,
-        'BIGCOMMERCE_API_ERROR',
-        response.status,
-      );
-    }
-
-    return response.json() as Promise<T>;
-  }
-
-  // ============================================
-  // Product Operations
-  // ============================================
-
-  async getProduct(handle: string): Promise<Product | undefined> {
-    try {
-      const data = await this.fetchApi<{ data: any[] }>(`/api/storefront/products?include=variants,options,images&keyword=${encodeURIComponent(handle)}`);
-      const product = data.data?.[0];
-      return product ? transformProduct(product, this.currencyCode) : undefined;
-    } catch {
-      return undefined;
-    }
-  }
-
-  async getProducts(options?: GetProductsOptions): Promise<Product[]> {
-    const limit = options?.first ?? 20;
-    let path = `/api/storefront/products?include=variants,options,images&limit=${limit}`;
-    if (options?.query) path += `&keyword=${encodeURIComponent(options.query)}`;
-
-    const data = await this.fetchApi<{ data: any[] }>(path);
-    return (data.data ?? []).map((p) => transformProduct(p, this.currencyCode));
-  }
-
-  async getProductRecommendations(_productId: string): Promise<Product[]> {
-    return []; // BigCommerce doesn't have a Storefront recommendation API
-  }
-
-  // ============================================
-  // Collection Operations (BigCommerce Categories)
-  // ============================================
-
-  async getCollection(handle: string): Promise<Collection | undefined> {
-    try {
-      const data = await this.fetchApi<{ data: any[] }>(`/api/storefront/categories?url=/${handle}/`);
-      const cat = data.data?.[0];
-      return cat ? transformCollection(cat) : undefined;
-    } catch {
-      return undefined;
-    }
-  }
-
-  async getCollections(options?: GetCollectionsOptions): Promise<Collection[]> {
-    const limit = options?.limit ?? 50;
-    const data = await this.fetchApi<{ data: any[] }>(`/api/storefront/categories?limit=${limit}`);
-    return (data.data ?? []).map(transformCollection);
-  }
-
-  async getCollectionProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
-    const limit = options?.first ?? 20;
-    const data = await this.fetchApi<{ data: any[] }>(
-      `/api/storefront/products?include=variants,options,images&categories:in=${handle}&limit=${limit}`,
-    );
-    return (data.data ?? []).map((p) => transformProduct(p, this.currencyCode));
-  }
-
-  // ============================================
-  // Category Operations
-  // ============================================
-
-  async getCategory(idOrHandle: string): Promise<ProductCategory | undefined> {
-    return this.getCollection(idOrHandle) as any;
-  }
-
-  async getCategories(options?: GetCategoriesOptions): Promise<ProductCategory[]> {
-    return this.getCollections(options) as any;
-  }
-
-  async getCategoryProducts(handle: string, options?: CollectionProductsOptions): Promise<Product[]> {
-    return this.getCollectionProducts(handle, options);
-  }
-
-  // ============================================
-  // Cart Operations
-  // ============================================
-
-  async createCart(): Promise<Cart> {
-    const data = await this.fetchApi<{ data: any }>('/api/storefront/carts', {
-      method: 'POST',
-      body: JSON.stringify({ line_items: [] }),
-    });
-    return transformCart(data.data ?? data, this.currencyCode);
-  }
-
-  async getCart(cartId: string): Promise<Cart | undefined> {
-    try {
-      const data = await this.fetchApi<{ data: any }>(`/api/storefront/carts/${cartId}?include=line_items.physical_items.options`);
-      return transformCart(data.data ?? data, this.currencyCode);
-    } catch {
-      return undefined;
-    }
-  }
-
-  async addToCart(cartId: string, lines: CartLineInput[]): Promise<Cart> {
-    const lineItems = lines.map((l) => ({
-      product_id: parseInt(l.merchandiseId, 10),
-      quantity: l.quantity,
-    }));
-
-    const data = await this.fetchApi<{ data: any }>(`/api/storefront/carts/${cartId}/items`, {
-      method: 'POST',
-      body: JSON.stringify({ line_items: lineItems }),
-    });
-
-    return transformCart(data.data ?? data, this.currencyCode);
-  }
-
-  async removeFromCart(cartId: string, lineIds: string[]): Promise<Cart> {
-    for (const lineId of lineIds) {
-      await this.fetchApi(`/api/storefront/carts/${cartId}/items/${lineId}`, { method: 'DELETE' });
-    }
-
-    const cart = await this.getCart(cartId);
-    if (!cart) throw new ProviderAPIError('Cart not found after removal', 'BIGCOMMERCE_CART_ERROR');
-    return cart;
-  }
-
-  async updateCart(cartId: string, lines: CartLineUpdate[]): Promise<Cart> {
-    for (const line of lines) {
-      await this.fetchApi(`/api/storefront/carts/${cartId}/items/${line.id}`, {
-        method: 'PUT',
-        body: JSON.stringify({ line_item: { quantity: line.quantity } }),
-      });
-    }
-
-    const cart = await this.getCart(cartId);
-    if (!cart) throw new ProviderAPIError('Cart not found after update', 'BIGCOMMERCE_CART_ERROR');
-    return cart;
-  }
-
-  // ============================================
-  // Checkout Operations (Hosted)
-  // ============================================
-
-  async completeCheckout(_cartId: string): Promise<Order> {
-    throw new ProviderAPIError(
-      'BigCommerce uses Embedded Checkout. Redirect the buyer to cart.checkoutUrl.',
-      'BIGCOMMERCE_HOSTED_CHECKOUT',
-    );
-  }
-
-  async getShippingMethods(_cartId: string): Promise<ShippingMethod[]> {
-    return [];
-  }
-
-  async getRegionCountries(): Promise<import('@thorprovider/types').Country[]> {
-    return [];
-  }
-
-  async addShippingMethod(_cartId: string, _methodId: string): Promise<Cart> {
-    throw new ProviderAPIError('BigCommerce handles shipping in Embedded Checkout.', 'BIGCOMMERCE_HOSTED_CHECKOUT');
-  }
-
-  async initiatePaymentSession(_cartId: string, _providerId: string): Promise<void> {
-    throw new ProviderAPIError('BigCommerce handles payment in Embedded Checkout.', 'BIGCOMMERCE_HOSTED_CHECKOUT');
-  }
-
-  async applyDiscountCode(cartId: string, code: string): Promise<Cart> {
-    const data = await this.fetchApi<{ data: any }>(`/api/storefront/carts/${cartId}/coupons`, {
-      method: 'POST',
-      body: JSON.stringify({ coupon_code: code }),
-    });
-    return transformCart(data.data ?? data, this.currencyCode);
-  }
-
-  async removeDiscountCode(cartId: string, code: string): Promise<Cart> {
-    await this.fetchApi(`/api/storefront/carts/${cartId}/coupons/${encodeURIComponent(code)}`, { method: 'DELETE' });
-    const cart = await this.getCart(cartId);
-    if (!cart) throw new ProviderAPIError('Cart not found after coupon removal', 'BIGCOMMERCE_CART_ERROR');
-    return cart;
-  }
-
-  // ============================================
-  // Customer, Order, Payment, Inventory, Admin
-  // ============================================
-
-  async getOrders(_options: GetOrdersOptions): Promise<Order[]> {
-    return [];
-  }
-
-  async getPaymentMethods(_options: PaymentMethodsOptions): Promise<PaymentMethod[]> {
-    return [];
-  }
-
-  async getStockLocations(): Promise<StockLocation[]> { return []; }
-  async checkInventoryLevels(): Promise<InventoryLevel[]> { return []; }
-  async validateCartStock(): Promise<StockValidation> { return { allAvailable: true, unavailableItems: [] }; }
-  async getFulfillmentOptions(): Promise<FulfillmentOption[]> { return []; }
-
-  async cancelOrder(_orderId: string): Promise<Order> {
-    throw new ProviderAPIError('Order cancellation requires BigCommerce Management API.', 'BIGCOMMERCE_ADMIN_REQUIRED');
-  }
-  async createFulfillment(_orderId: string): Promise<void> {
-    throw new ProviderAPIError('Fulfillment requires BigCommerce Management API.', 'BIGCOMMERCE_ADMIN_REQUIRED');
-  }
-  async createRefund(_orderId: string): Promise<void> {
-    throw new ProviderAPIError('Refunds require BigCommerce Management API.', 'BIGCOMMERCE_ADMIN_REQUIRED');
-  }
-  async getAdminOrders(): Promise<{ orders: Order[]; count: number }> { return { orders: [], count: 0 }; }
-
-  async getStorefrontContext(): Promise<StorefrontContext> {
-    return {
-      id: this.channelId,
-      name: `BigCommerce Store ${this.storeHash}`,
-      platformType: 'bigcommerce',
-      requiresProductScoping: false,
-      currencyCode: this.currencyCode,
-    };
-  }
-
-  isStorefrontRequired(): boolean { return false; }
-}