@thorprovider/medusa-extended 1.0.0

package/src/admin.ts

@@ -0,0 +1,441 @@
+/**
+ * @fileoverview Medusa Multi-Tenant Admin Client
+ * @module @thorprovider/adapters/providers/medusa/admin
+ *
+ * Wrapper methods for all `/admin/thor/` endpoints defined in the Thor Commerce
+ * multi-tenant API contract.  Requires an admin API key (`adminConfig.apiKey`)
+ * to be provided when creating the Medusa provider.
+ *
+ * Every method performs a raw `fetch` against the Medusa backend using the
+ * admin API key (`x-medusa-access-token`) — the Medusa JS-SDK's admin client
+ * does not expose these custom Thor plugin routes, so we use direct HTTP calls.
+ *
+ * Endpoint reference: `multitenant-api-contract.md`
+ */
+
+import type {
+  GetChannelCustomersOptions,
+  GetChannelCustomersResponse,
+  GetChannelApiKeysResponse,
+  GetChannelCategoriesOptions,
+  GetChannelCategoriesResponse,
+  GetCategorySalesChannelsResponse,
+  AssignCategoriesToChannelsBody,
+  AssignCategoriesToChannelsResponse,
+  UnassignCategoriesFromChannelsBody,
+  UnassignCategoriesFromChannelsResponse,
+  GetCollectionSalesChannelsResponse,
+  AssignCollectionsToChannelsBody,
+  AssignCollectionsToChannelsResponse,
+  UnassignCollectionsFromChannelsBody,
+  UnassignCollectionsFromChannelsResponse,
+  GetAdminStorefrontConfigResponse,
+  UpdateStorefrontConfigBody,
+  UpdateStorefrontConfigResponse,
+  GetAdminSiteConfigResponse,
+  UpdateSiteConfigBody,
+  UpdateSiteConfigResponse,
+  GetAdminSiteConfigHistoryOptions,
+  GetAdminSiteConfigHistoryResponse,
+  RestoreSiteConfigResponse,
+} from '@thorprovider/types';
+import { createLogger, ProviderAPIError } from '@thorprovider/adapters';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+type FetchMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+
+/**
+ * Configuration required to instantiate the admin client.
+ */
+export interface MedusaAdminClientConfig {
+  /** Medusa backend base URL */
+  baseUrl: string;
+  /** Secret admin API key (x-medusa-access-token) */
+  apiKey: string;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// MedusaAdminClient
+// ---------------------------------------------------------------------------
+
+/**
+ * HTTP client for Thor Commerce multi-tenant admin endpoints (`/admin/thor/`).
+ *
+ * All methods throw `ProviderAPIError` on non-2xx responses.
+ *
+ * @example
+ * ```typescript
+ * const admin = new MedusaAdminClient({
+ *   baseUrl: process.env.MEDUSA_BACKEND_URL!,
+ *   apiKey: process.env.MEDUSA_ADMIN_API_KEY!,
+ * });
+ *
+ * const { customers } = await admin.getChannelCustomers('sc_01JXXXXX');
+ * ```
+ */
+export class MedusaAdminClient {
+  private baseUrl: string;
+  private apiKey: string;
+  private logger: ReturnType<typeof createLogger>;
+
+  constructor(config: MedusaAdminClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, '');
+    this.apiKey = config.apiKey;
+    this.logger = createLogger('MedusaAdminClient', config.debug);
+  }
+
+  // -----------------------------------------------------------------------
+  // Private — HTTP helper
+  // -----------------------------------------------------------------------
+
+  private async request<T>(
+    method: FetchMethod,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    this.logger.debug(`[admin] ${method} ${path}`);
+
+    const headers: Record<string, string> = {
+      'x-medusa-access-token': this.apiKey,
+      'Content-Type': 'application/json',
+    };
+
+    const init: RequestInit = {
+      method,
+      headers,
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    };
+
+    let response: Response;
+    try {
+      response = await fetch(url, init);
+    } catch (networkError: any) {
+      throw new ProviderAPIError(
+        `[admin] Network error on ${method} ${path}: ${networkError.message}`,
+        'NETWORK_ERROR',
+        networkError,
+      );
+    }
+
+    if (!response.ok) {
+      let message = `HTTP ${response.status}`;
+      try {
+        const json = await response.json();
+        message = json?.message ?? message;
+      } catch {
+        // ignore parse errors
+      }
+      throw new ProviderAPIError(
+        `[admin] ${method} ${path} failed: ${message}`,
+        `ADMIN_API_${response.status}`,
+        response.status,
+      );
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.1 — Sales Channel: Customers
+  // -----------------------------------------------------------------------
+
+  /**
+   * Paginated list of customers linked to a sales channel.
+   *
+   * `GET /admin/thor/sales-channels/:id/customers`
+   */
+  async getChannelCustomers(
+    salesChannelId: string,
+    options: GetChannelCustomersOptions = {},
+  ): Promise<GetChannelCustomersResponse> {
+    const { limit = 20, offset = 0 } = options;
+    return this.request<GetChannelCustomersResponse>(
+      'GET',
+      `/admin/thor/sales-channels/${salesChannelId}/customers?limit=${limit}&offset=${offset}`,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.2 — Sales Channel: API Keys
+  // -----------------------------------------------------------------------
+
+  /**
+   * Publishable API keys associated with a sales channel.
+   *
+   * `GET /admin/thor/sales-channels/:id/api-keys`
+   */
+  async getChannelApiKeys(salesChannelId: string): Promise<GetChannelApiKeysResponse> {
+    return this.request<GetChannelApiKeysResponse>(
+      'GET',
+      `/admin/thor/sales-channels/${salesChannelId}/api-keys`,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.3 — Sales Channel: Categories
+  // -----------------------------------------------------------------------
+
+  /**
+   * Product categories assigned to a sales channel.
+   *
+   * `GET /admin/thor/sales-channels/:id/categories`
+   */
+  async getChannelCategories(
+    salesChannelId: string,
+    options: GetChannelCategoriesOptions = {},
+  ): Promise<GetChannelCategoriesResponse> {
+    const { limit = 20, offset = 0, include_descendants = false } = options;
+    const qs = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset),
+      include_descendants: String(include_descendants),
+    });
+    return this.request<GetChannelCategoriesResponse>(
+      'GET',
+      `/admin/thor/sales-channels/${salesChannelId}/categories?${qs}`,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.4 — Category: Sales Channels
+  // -----------------------------------------------------------------------
+
+  /**
+   * Sales channels to which a category is assigned.
+   *
+   * `GET /admin/thor/categories/:id/sales-channels`
+   */
+  async getCategorySalesChannels(
+    categoryId: string,
+  ): Promise<GetCategorySalesChannelsResponse> {
+    return this.request<GetCategorySalesChannelsResponse>(
+      'GET',
+      `/admin/thor/categories/${categoryId}/sales-channels`,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.5 — Category: Assign to Sales Channels
+  // -----------------------------------------------------------------------
+
+  /**
+   * Assign a category to one or more sales channels (idempotent).
+   *
+   * `POST /admin/thor/categories/:id/sales-channels`
+   */
+  async assignCategoryToChannels(
+    categoryId: string,
+    body: AssignCategoriesToChannelsBody,
+  ): Promise<AssignCategoriesToChannelsResponse> {
+    return this.request<AssignCategoriesToChannelsResponse>(
+      'POST',
+      `/admin/thor/categories/${categoryId}/sales-channels`,
+      body,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.6 — Category: Unassign from Sales Channels
+  // -----------------------------------------------------------------------
+
+  /**
+   * Remove category assignment from one or more sales channels (idempotent).
+   *
+   * `DELETE /admin/thor/categories/:id/sales-channels`
+   */
+  async unassignCategoryFromChannels(
+    categoryId: string,
+    body: UnassignCategoriesFromChannelsBody,
+  ): Promise<UnassignCategoriesFromChannelsResponse> {
+    return this.request<UnassignCategoriesFromChannelsResponse>(
+      'DELETE',
+      `/admin/thor/categories/${categoryId}/sales-channels`,
+      body,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.7 — Collection: Sales Channels
+  // -----------------------------------------------------------------------
+
+  /**
+   * Sales channels to which a collection is assigned.
+   *
+   * `GET /admin/thor/collections/:id/sales-channels`
+   */
+  async getCollectionSalesChannels(
+    collectionId: string,
+  ): Promise<GetCollectionSalesChannelsResponse> {
+    return this.request<GetCollectionSalesChannelsResponse>(
+      'GET',
+      `/admin/thor/collections/${collectionId}/sales-channels`,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.8 — Collection: Assign to Sales Channels
+  // -----------------------------------------------------------------------
+
+  /**
+   * Assign a collection to one or more sales channels (idempotent).
+   *
+   * `POST /admin/thor/collections/:id/sales-channels`
+   */
+  async assignCollectionToChannels(
+    collectionId: string,
+    body: AssignCollectionsToChannelsBody,
+  ): Promise<AssignCollectionsToChannelsResponse> {
+    return this.request<AssignCollectionsToChannelsResponse>(
+      'POST',
+      `/admin/thor/collections/${collectionId}/sales-channels`,
+      body,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.9 — Collection: Unassign from Sales Channels
+  // -----------------------------------------------------------------------
+
+  /**
+   * Remove collection assignment from one or more sales channels (idempotent).
+   *
+   * `DELETE /admin/thor/collections/:id/sales-channels`
+   */
+  async unassignCollectionFromChannels(
+    collectionId: string,
+    body: UnassignCollectionsFromChannelsBody,
+  ): Promise<UnassignCollectionsFromChannelsResponse> {
+    return this.request<UnassignCollectionsFromChannelsResponse>(
+      'DELETE',
+      `/admin/thor/collections/${collectionId}/sales-channels`,
+      body,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.10 — Storefront Config: Read
+  // -----------------------------------------------------------------------
+
+  /**
+   * Read the visual storefront configuration for a channel.
+   * `:id` is the `sales_channel_id`.
+   *
+   * `GET /admin/thor/storefront-config/:id`
+   */
+  async getStorefrontConfig(
+    salesChannelId: string,
+  ): Promise<GetAdminStorefrontConfigResponse> {
+    return this.request<GetAdminStorefrontConfigResponse>(
+      'GET',
+      `/admin/thor/storefront-config/${salesChannelId}`,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.11 — Storefront Config: Update
+  // -----------------------------------------------------------------------
+
+  /**
+   * Update the visual storefront configuration for a channel.
+   * Triggers the `storefront_config.updated` event → ISR webhook.
+   *
+   * `PUT /admin/thor/storefront-config/:id`
+   */
+  async updateStorefrontConfig(
+    salesChannelId: string,
+    body: UpdateStorefrontConfigBody,
+  ): Promise<UpdateStorefrontConfigResponse> {
+    return this.request<UpdateStorefrontConfigResponse>(
+      'PUT',
+      `/admin/thor/storefront-config/${salesChannelId}`,
+      body,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.12 — Site Designer Config: Read
+  // -----------------------------------------------------------------------
+
+  /**
+   * Read the active Site Designer configuration for a channel, including the
+   * last 10 history entries.
+   *
+   * `GET /admin/thor/site-config/:sales_channel_id`
+   */
+  async getSiteConfig(salesChannelId: string): Promise<GetAdminSiteConfigResponse> {
+    return this.request<GetAdminSiteConfigResponse>(
+      'GET',
+      `/admin/thor/site-config/${salesChannelId}`,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.13 — Site Designer Config: Update
+  // -----------------------------------------------------------------------
+
+  /**
+   * Update the Site Designer configuration for a channel.
+   * Creates a new history entry on every PUT.
+   *
+   * `PUT /admin/thor/site-config/:sales_channel_id`
+   */
+  async updateSiteConfig(
+    salesChannelId: string,
+    body: UpdateSiteConfigBody,
+  ): Promise<UpdateSiteConfigResponse> {
+    return this.request<UpdateSiteConfigResponse>(
+      'PUT',
+      `/admin/thor/site-config/${salesChannelId}`,
+      body,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.14 — Site Designer Config: History
+  // -----------------------------------------------------------------------
+
+  /**
+   * Full paginated history of Site Designer versions for a channel.
+   * Entries are immutable — they are never deleted.
+   *
+   * `GET /admin/thor/site-config/:sales_channel_id/history`
+   */
+  async getSiteConfigHistory(
+    salesChannelId: string,
+    options: GetAdminSiteConfigHistoryOptions = {},
+  ): Promise<GetAdminSiteConfigHistoryResponse> {
+    const { limit = 20, offset = 0 } = options;
+    return this.request<GetAdminSiteConfigHistoryResponse>(
+      'GET',
+      `/admin/thor/site-config/${salesChannelId}/history?limit=${limit}&offset=${offset}`,
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // 3.15 — Site Designer Config: Restore
+  // -----------------------------------------------------------------------
+
+  /**
+   * Restore a previous Site Designer version.
+   * Internally runs the update workflow with the stored config of the target
+   * version — this creates a **new** history entry and does NOT mutate past
+   * entries.
+   *
+   * `POST /admin/thor/site-config/:sales_channel_id/restore/:version`
+   */
+  async restoreSiteConfig(
+    salesChannelId: string,
+    version: string,
+  ): Promise<RestoreSiteConfigResponse> {
+    return this.request<RestoreSiteConfigResponse>(
+      'POST',
+      `/admin/thor/site-config/${salesChannelId}/restore/${encodeURIComponent(version)}`,
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @thorprovider/medusa-extended
+ * Thor Commerce multi-tenant admin extensions for Medusa
+ */
+
+export { MedusaAdminClient } from './admin';
+export type { MedusaAdminClientConfig } from './admin';

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "moduleResolution": "bundler",
+    "baseUrl": "."
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: {
+    'index': 'src/index.ts'
+  },
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  onSuccess: process.env.SKIP_TYPE_CHECK === 'true' ? undefined : 'tsc --noEmit --skipLibCheck'
+})