@thorprovider/adapters 4.2.0 → 4.3.0

package/src/providers/medusa/admin.ts

@@ -0,0 +1,442 @@
+/**
+ * @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 } from '../../core/logger';
+import { ProviderAPIError } from '../../core/errors';
+
+// ---------------------------------------------------------------------------
+// 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/providers/medusa/auth.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Tests for MedusaAuthProvider.linkCustomerToChannel
+ *
+ * Uses msw to intercept fetch, a minimal Medusa SDK stub, and a custom
+ * storage stub to inject a pre-set JWT token.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { http, HttpResponse } from 'msw'
+import { server } from '../stelorder/client.test-helpers'
+import { MedusaAuthProvider } from './auth'
+
+const BASE = 'https://medusa.example.com'
+const PUB_KEY = 'pk_test_123'
+const TOKEN = 'jwt-bearer-token'
+
+// ---------------------------------------------------------------------------
+// Minimal SDK stub — we only test the linkCustomerToChannel raw-fetch path,
+// so the SDK itself does not need to do anything.
+// ---------------------------------------------------------------------------
+
+function makeSdkStub(): any {
+  return {
+    auth: {},
+    store: { customer: {} },
+  } as any
+}
+
+// ---------------------------------------------------------------------------
+// Custom storage stub — provides a pre-set token to the auth provider
+// ---------------------------------------------------------------------------
+
+function makeStorageWithToken(token: string | null) {
+  let stored: string | null = token
+  return {
+    getItem: (_key: string) => Promise.resolve(stored),
+    setItem: (_key: string, value: string) => { stored = value; return Promise.resolve() },
+    removeItem: (_key: string) => { stored = null; return Promise.resolve() },
+  }
+}
+
+function makeAuthConfig(token: string | null = TOKEN) {
+  return {
+    method: 'jwt' as const,
+    storage: 'memory' as const,
+    customStorage: makeStorageWithToken(token),
+  }
+}
+
+function makeProvider(token: string | null = TOKEN) {
+  return new MedusaAuthProvider(makeSdkStub(), makeAuthConfig(token), false, BASE, PUB_KEY)
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('MedusaAuthProvider.linkCustomerToChannel', () => {
+  it('POST /store/thor/customers/me/channels with Authorization header when token present', async () => {
+    server.use(
+      http.post(`${BASE}/store/thor/customers/me/channels`, ({ request }) => {
+        expect(request.headers.get('x-publishable-api-key')).toBe(PUB_KEY)
+        expect(request.headers.get('Authorization')).toBe(`Bearer ${TOKEN}`)
+        return HttpResponse.json({ linked: true })
+      }),
+    )
+
+    const result = await makeProvider().linkCustomerToChannel()
+    expect(result.linked).toBe(true)
+  })
+
+  it('POST without Authorization header when no token in storage', async () => {
+    server.use(
+      http.post(`${BASE}/store/thor/customers/me/channels`, ({ request }) => {
+        expect(request.headers.get('Authorization')).toBeNull()
+        expect(request.headers.get('x-publishable-api-key')).toBe(PUB_KEY)
+        return HttpResponse.json({ linked: true })
+      }),
+    )
+
+    const result = await makeProvider(null).linkCustomerToChannel()
+    expect(result.linked).toBe(true)
+  })
+
+  it('returns { linked: true, reason: "already_linked" } on duplicate link', async () => {
+    server.use(
+      http.post(`${BASE}/store/thor/customers/me/channels`, () =>
+        HttpResponse.json({ linked: true, reason: 'already_linked' }),
+      ),
+    )
+
+    const result = await makeProvider().linkCustomerToChannel()
+    expect(result.linked).toBe(true)
+    expect(result.reason).toBe('already_linked')
+  })
+
+  it('throws ProviderAPIError with NOT_AUTHENTICATED on 401', async () => {
+    server.use(
+      http.post(`${BASE}/store/thor/customers/me/channels`, () =>
+        HttpResponse.json({ message: 'Unauthorized' }, { status: 401 }),
+      ),
+    )
+
+    await expect(makeProvider().linkCustomerToChannel()).rejects.toMatchObject({
+      name: 'ProviderAPIError',
+      provider: 'NOT_AUTHENTICATED',
+      status: 401,
+    })
+  })
+
+  it('throws ProviderAPIError with CHANNEL_RESOLUTION_FAILED on 400', async () => {
+    server.use(
+      http.post(`${BASE}/store/thor/customers/me/channels`, () =>
+        HttpResponse.json({ message: 'No sales channel found for publishable key' }, { status: 400 }),
+      ),
+    )
+
+    await expect(makeProvider().linkCustomerToChannel()).rejects.toMatchObject({
+      name: 'ProviderAPIError',
+      provider: 'CHANNEL_RESOLUTION_FAILED',
+      status: 400,
+    })
+  })
+
+  it('throws ProviderAPIError with LINK_CHANNEL_FAILED on unexpected status', async () => {
+    server.use(
+      http.post(`${BASE}/store/thor/customers/me/channels`, () =>
+        HttpResponse.json({ message: 'Service unavailable' }, { status: 503 }),
+      ),
+    )
+
+    await expect(makeProvider().linkCustomerToChannel()).rejects.toMatchObject({
+      name: 'ProviderAPIError',
+      provider: 'LINK_CHANNEL_FAILED',
+    })
+  })
+})

package/src/providers/medusa/auth.ts

@@ -19,6 +19,7 @@ import type {
   CreateAddressData,
   PasswordResetRequest,
   PasswordResetConfirm,
+  LinkCustomerToChannelResponse,
 } from '@thorprovider/types';
 import { createLogger } from '../../core/logger';
 import { ProviderAPIError } from '../../core/errors';
@@ -120,12 +121,18 @@ export class MedusaAuthProvider implements AuthProvider {
   private logger: ReturnType<typeof createLogger>;
   private authConfig: AuthConfig;
   private storageManager: AuthStorageManager;
+  /** Medusa backend base URL — needed for raw fetch calls */
+  private baseUrl: string;
+  /** Publishable API key — sent as x-publishable-api-key on store calls */
+  private publishableKey: string;
   
-  constructor(sdk: Medusa, authConfig: AuthConfig, debug = false) {
+  constructor(sdk: Medusa, authConfig: AuthConfig, debug = false, baseUrl = '', publishableKey = '') {
     this.sdk = sdk;
     this.authConfig = authConfig;
     this.logger = createLogger('MedusaAuthProvider', debug);
     this.storageManager = new AuthStorageManager(authConfig);
+    this.baseUrl = baseUrl;
+    this.publishableKey = publishableKey;
     
     this.logger.info('Medusa Auth Provider initialized', {
       method: authConfig.method,
@@ -493,4 +500,92 @@ export class MedusaAuthProvider implements AuthProvider {
       undefined
     );
   }
+
+  // ========================================
+  // Multi-Tenant — Channel Link
+  // ========================================
+
+  /**
+   * Link the currently authenticated customer to the storefront's sales channel.
+   *
+   * Must be called immediately after a successful `login()` so the customer
+   * appears in the admin panel of the correct storefront channel.
+   *
+   * Implements `POST /store/thor/customers/me/channels`.
+   * Idempotent — returns `{ linked: false, reason: 'already_linked' }` when
+   * the link already exists.
+   *
+   * @throws {ProviderAPIError} When not authenticated (401) or channel cannot
+   *   be resolved from the publishable key (400).
+   */
+  async linkCustomerToChannel(): Promise<LinkCustomerToChannelResponse> {
+    this.logger.debug('linkCustomerToChannel');
+
+    if (!this.baseUrl || !this.publishableKey) {
+      throw new ProviderAPIError(
+        'linkCustomerToChannel requires baseUrl and publishableKey to be set on the auth provider.',
+        'CONFIGURATION_ERROR',
+        undefined
+      );
+    }
+
+    // Retrieve the JWT token for the Authorization header.
+    // Falls back to the SDK-managed token (session or JWT storage).
+    const token = await this.storageManager.getToken();
+
+    const headers: Record<string, string> = {
+      'x-publishable-api-key': this.publishableKey,
+      'Content-Type': 'application/json',
+    };
+
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+
+    try {
+      const url = `${this.baseUrl}/store/thor/customers/me/channels`;
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+      });
+
+      if (response.status === 401) {
+        throw new ProviderAPIError(
+          'linkCustomerToChannel: not authenticated. Call login() first.',
+          'NOT_AUTHENTICATED',
+          401
+        );
+      }
+
+      if (response.status === 400) {
+        const body = await response.json().catch(() => ({}));
+        throw new ProviderAPIError(
+          `linkCustomerToChannel: could not resolve sales channel from publishable key. ${body?.message ?? ''}`.trim(),
+          'CHANNEL_RESOLUTION_FAILED',
+          400
+        );
+      }
+
+      if (!response.ok) {
+        const body = await response.json().catch(() => ({}));
+        throw new ProviderAPIError(
+          `linkCustomerToChannel failed with status ${response.status}: ${body?.message ?? 'Unknown error'}`,
+          'LINK_CHANNEL_FAILED',
+          response.status
+        );
+      }
+
+      const data = await response.json() as LinkCustomerToChannelResponse;
+      this.logger.info('Customer linked to channel', { linked: data.linked, reason: data.reason });
+      return data;
+    } catch (error: any) {
+      if (error instanceof ProviderAPIError) throw error;
+      this.logger.error('linkCustomerToChannel failed', error);
+      throw new ProviderAPIError(
+        `linkCustomerToChannel failed: ${error.message}`,
+        'LINK_CHANNEL_FAILED',
+        error
+      );
+    }
+  }
 }