@thorprovider/adapters 4.2.0 → 4.3.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; } });