@thorprovider/medusa-extended 1.11.8 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/medusa-extended",
-  "version": "1.11.8",
+  "version": "1.12.0",
   "description": "Thor Commerce multi-tenant admin extensions for Medusa v2",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@thorprovider/adapters": "^5.0.8",
-    "@thorprovider/types": "^5.3.8"
+    "@thorprovider/types": "^5.4.0"
   },
   "devDependencies": {
     "msw": "^2.12.3",

package/src/dropshipper.live-smoke.test.ts

@@ -23,6 +23,7 @@ import type {
   ExtendedCreateDropshipperOrderBody,
   GetDropshipperProductsResponse,
   GetDropshipperCustomersResponse,
+  GetDropshipperShippingOptionsBody,
   GetDropshipperShippingOptionsResponse,
   GetDropshipperAccountResponse,
 } from '@thorprovider/types'
@@ -76,6 +77,28 @@ if (!runLive) {
     }
   }
 
+  /** Build a shipping-options request body for a variant (contract v2 POST). */
+  function buildShippingOptionsBody(
+    customerId: string,
+    variantId: string,
+    currencyCode: string,
+    address?: Partial<GetDropshipperShippingOptionsBody['shipping_address']>,
+  ): GetDropshipperShippingOptionsBody {
+    return {
+      customer_id: customerId,
+      currency_code: currencyCode,
+      shipping_address: {
+        address_1: '123 Test Street',
+        city: 'Test City',
+        province: 'Nuevo Leon',
+        postal_code: '00000',
+        country_code: 'mx',
+        ...address,
+      },
+      items: [{ variant_id: variantId, quantity: 1 }],
+    }
+  }
+
   beforeAll(async () => {
     // Stop MSW so real HTTP requests reach the backend
     server.close()
@@ -95,9 +118,18 @@ if (!runLive) {
   describe('Test data discovery', () => {
     let products: GetDropshipperProductsResponse['products']
     let customers: GetDropshipperCustomersResponse['customers']
-    let shippingOptions: GetDropshipperShippingOptionsResponse['shipping_options']
+    let shippingGroups: GetDropshipperShippingOptionsResponse['groups']
     let account: GetDropshipperAccountResponse['account']
 
+    function getFirstVariantId(): string {
+      for (const product of products) {
+        if (product.variants && product.variants.length > 0) {
+          return product.variants[0].id
+        }
+      }
+      throw new Error('No products with variants found')
+    }
+
     it('fetches products to find valid variant IDs', async () => {
       const res = await client.getProducts({ limit: 5 })
       expect(res.products.length).toBeGreaterThan(0)
@@ -116,15 +148,15 @@ if (!runLive) {
       account = res.account
     })
 
-    it('fetches shipping options for the account currency', async () => {
-      const res = await client.getOrderShippingOptions({
-        currency_code: account.currency_code,
-      })
-      expect(res.shipping_options.length).toBeGreaterThan(0)
-      shippingOptions = res.shipping_options
+    it('fetches shipping groups for the account currency', async () => {
+      const res = await client.getOrderShippingOptions(
+        buildShippingOptionsBody(customers[0].id, getFirstVariantId(), account.currency_code),
+      )
+      expect(res.groups.length).toBeGreaterThan(0)
+      shippingGroups = res.groups
     })
 
-    it('fetches shipping options with country code (geozone filter)', async () => {
+    it('fetches shipping groups with country code (geozone filter)', async () => {
       // Use the customer's default shipping address country if available
       const customerDetail = await client.getCustomer(customers[0].id)
       const addr = customerDetail.customer?.addresses?.find((a) => a.is_default_shipping)
@@ -133,15 +165,16 @@ if (!runLive) {
         return
       }
 
-      const res = await client.getOrderShippingOptions({
-        currency_code: account.currency_code,
-        country_code: addr.country_code,
-        province: addr.province ?? undefined,
-        city: addr.city ?? undefined,
-      })
-      expect(res.shipping_options).toBeInstanceOf(Array)
+      const res = await client.getOrderShippingOptions(
+        buildShippingOptionsBody(customers[0].id, getFirstVariantId(), account.currency_code, {
+          country_code: addr.country_code,
+          province: addr.province ?? undefined,
+          city: addr.city ?? undefined,
+        }),
+      )
+      expect(res.groups).toBeInstanceOf(Array)
       console.log(
-        `Shipping options for ${addr.country_code}/${addr.province ?? 'any'}/${addr.city ?? 'any'}: ${res.shipping_options.length} found`,
+        `Shipping groups for ${addr.country_code}/${addr.province ?? 'any'}/${addr.city ?? 'any'}: ${res.groups.length} found`,
       )
     })
   })
@@ -154,7 +187,7 @@ if (!runLive) {
     let products: GetDropshipperProductsResponse['products']
     let customers: GetDropshipperCustomersResponse['customers']
     let account: GetDropshipperAccountResponse['account']
-    let shippingOptions: GetDropshipperShippingOptionsResponse['shipping_options']
+    let shippingGroups: GetDropshipperShippingOptionsResponse['groups']
     let createdOrderIds: string[] = []
 
     beforeAll(async () => {
@@ -167,10 +200,11 @@ if (!runLive) {
       customers = customersRes.customers
       account = accountRes.account
 
-      const shippingRes = await client.getOrderShippingOptions({
-        currency_code: account.currency_code,
-      })
-      shippingOptions = shippingRes.shipping_options
+      const variantId = getFirstVariantId()
+      const shippingRes = await client.getOrderShippingOptions(
+        buildShippingOptionsBody(customers[0].id, variantId, account.currency_code),
+      )
+      shippingGroups = shippingRes.groups
     })
 
     afterAll(async () => {
@@ -226,19 +260,29 @@ if (!runLive) {
       console.log(`Created order ${res.order.display_id} (${res.order.id}) — total: ${res.order.total}`)
     })
 
-    it('creates an order with shipping_method_id', async () => {
-      if (shippingOptions.length === 0) {
-        console.log('Skipping: no shipping options available')
+    it('creates an order with shipping_groups', async () => {
+      if (shippingGroups.length === 0) {
+        console.log('Skipping: no shipping groups available')
         return
       }
 
-      const body = buildOrderBody({ shipping_method_id: shippingOptions[0].id })
+      const shippingGroupsInput = shippingGroups
+        .map((g) => {
+          const option = g.options.find((o) => o.is_default) ?? g.options[0]
+          if (!option) return null
+          return { products: g.products, option_id: option.id }
+        })
+        .filter((g): g is { products: string[]; option_id: string } => g !== null)
+
+      const body = buildOrderBody({ shipping_groups: shippingGroupsInput })
       const res = await client.createOrder(body)
       expect(res.order.id).toBeTruthy()
       expect(res.order.status).toBe('pending')
+      expect(res.order.shipping_methods.length).toBe(shippingGroupsInput.length)
+      expect(res.order.shipping_total).toBeGreaterThan(0)
 
       createdOrderIds.push(res.order.id)
-      console.log(`Created order with shipping method: ${shippingOptions[0].name}`)
+      console.log(`Created order with shipping groups: ${res.order.shipping_methods.map((m) => m.name).join(', ')}`)
     })
 
     it('creates an order with billing_address', async () => {
@@ -571,72 +615,82 @@ if (!runLive) {
 
   describe('Shipping options with geozone parameters', () => {
     let account: GetDropshipperAccountResponse['account']
+    let customerId: string
+    let variantId: string
 
     beforeAll(async () => {
-      const res = await client.getAccount()
-      account = res.account
+      const [accountRes, customersRes, productsRes] = await Promise.all([
+        client.getAccount(),
+        client.getCustomers({ limit: 1 }),
+        client.getProducts({ limit: 5 }),
+      ])
+      account = accountRes.account
+      customerId = customersRes.customers[0].id
+      const product = productsRes.products.find((p) => p.variants && p.variants.length > 0)
+      if (!product) throw new Error('No products with variants found')
+      variantId = product.variants[0].id
     })
 
-    it('returns shipping options with currency_code only', async () => {
-      const res = await client.getOrderShippingOptions({
-        currency_code: account.currency_code,
-      })
-      expect(res.shipping_options).toBeInstanceOf(Array)
-      console.log(`Shipping options (currency only): ${res.shipping_options.length} found`)
-      if (res.shipping_options.length > 0) {
-        expect(res.shipping_options[0]).toHaveProperty('id')
-        expect(res.shipping_options[0]).toHaveProperty('name')
-        expect(res.shipping_options[0]).toHaveProperty('amount')
+    it('returns shipping groups with currency only', async () => {
+      const res = await client.getOrderShippingOptions(
+        buildShippingOptionsBody(customerId, variantId, account.currency_code),
+      )
+      expect(res.groups).toBeInstanceOf(Array)
+      console.log(`Shipping groups (currency only): ${res.groups.length} found`)
+      if (res.groups.length > 0) {
+        const option = res.groups[0].options[0]
+        expect(option).toHaveProperty('id')
+        expect(option).toHaveProperty('name')
+        expect(option).toHaveProperty('amount')
       }
     })
 
-    it('returns shipping options filtered by country_code', async () => {
-      const res = await client.getOrderShippingOptions({
-        currency_code: account.currency_code,
-        country_code: 'mx',
-      })
-      expect(res.shipping_options).toBeInstanceOf(Array)
-      console.log(`Shipping options (MX): ${res.shipping_options.length} found`)
+    it('returns shipping groups filtered by country_code', async () => {
+      const res = await client.getOrderShippingOptions(
+        buildShippingOptionsBody(customerId, variantId, account.currency_code, { country_code: 'mx' }),
+      )
+      expect(res.groups).toBeInstanceOf(Array)
+      console.log(`Shipping groups (MX): ${res.groups.length} found`)
     })
 
-    it('returns shipping options filtered by country_code and province', async () => {
-      const res = await client.getOrderShippingOptions({
-        currency_code: account.currency_code,
-        country_code: 'mx',
-        province: 'Nuevo Leon',
-      })
-      expect(res.shipping_options).toBeInstanceOf(Array)
-      console.log(`Shipping options (MX/Nuevo Leon): ${res.shipping_options.length} found`)
+    it('returns shipping groups filtered by country_code and province', async () => {
+      const res = await client.getOrderShippingOptions(
+        buildShippingOptionsBody(customerId, variantId, account.currency_code, {
+          country_code: 'mx',
+          province: 'Nuevo Leon',
+        }),
+      )
+      expect(res.groups).toBeInstanceOf(Array)
+      console.log(`Shipping groups (MX/Nuevo Leon): ${res.groups.length} found`)
     })
 
-    it('returns shipping options filtered by country_code, province, and city', async () => {
-      const res = await client.getOrderShippingOptions({
-        currency_code: account.currency_code,
-        country_code: 'mx',
-        province: 'Nuevo Leon',
-        city: 'Monterrey',
-      })
-      expect(res.shipping_options).toBeInstanceOf(Array)
-      console.log(`Shipping options (MX/Nuevo Leon/Monterrey): ${res.shipping_options.length} found`)
+    it('returns shipping groups filtered by country_code, province, and city', async () => {
+      const res = await client.getOrderShippingOptions(
+        buildShippingOptionsBody(customerId, variantId, account.currency_code, {
+          country_code: 'mx',
+          province: 'Nuevo Leon',
+          city: 'Monterrey',
+        }),
+      )
+      expect(res.groups).toBeInstanceOf(Array)
+      console.log(`Shipping groups (MX/Nuevo Leon/Monterrey): ${res.groups.length} found`)
     })
 
     it('returns different results for different countries (geozone differentiation)', async () => {
       const [mxOptions, usOptions] = await Promise.all([
-        client.getOrderShippingOptions({
-          currency_code: account.currency_code,
-          country_code: 'mx',
-        }),
-        client.getOrderShippingOptions({
-          currency_code: account.currency_code,
-          country_code: 'us',
-        }),
+        client.getOrderShippingOptions(
+          buildShippingOptionsBody(customerId, variantId, account.currency_code, { country_code: 'mx' }),
+        ),
+        client.getOrderShippingOptions(
+          buildShippingOptionsBody(customerId, variantId, account.currency_code, { country_code: 'us' }),
+        ),
       ])
 
-      console.log(`MX options: ${mxOptions.shipping_options.length}, US options: ${usOptions.shipping_options.length}`)
+      console.log(`MX groups: ${mxOptions.groups.length}, US groups: ${usOptions.groups.length}`)
 
       // The options MAY differ by country — log the difference
-      const mxNames = mxOptions.shipping_options.map((o) => o.name).join(', ')
-      const usNames = usOptions.shipping_options.map((o) => o.name).join(', ')
+      const mxNames = mxOptions.groups.flatMap((g) => g.options.map((o) => o.name)).join(', ')
+      const usNames = usOptions.groups.flatMap((g) => g.options.map((o) => o.name)).join(', ')
       console.log(`MX: [${mxNames}]`)
       console.log(`US: [${usNames}]`)
     })

package/src/dropshipper.test.ts

@@ -590,23 +590,42 @@ describe('DropshipperClient.createOrder', () => {
 })
 
 describe('DropshipperClient.getOrderShippingOptions', () => {
-  it('GET /admin/thor/dropshipper/orders/shipping-options', async () => {
+  it('POST /admin/thor/dropshipper/orders/shipping-options with body', async () => {
     server.use(
-      http.get(`${BASE}/admin/thor/dropshipper/orders/shipping-options`, ({ request }) => {
+      http.post(`${BASE}/admin/thor/dropshipper/orders/shipping-options`, async ({ request }) => {
         requireBearerToken(request)
-        const url = new URL(request.url)
-        expect(url.searchParams.get('currency_code')).toBe('usd')
-        expect(url.searchParams.get('country_code')).toBe('us')
+        const body = await request.json() as any
+        expect(body.currency_code).toBe('usd')
+        expect(body.customer_id).toBe('cus_1')
+        expect(body.shipping_address.country_code).toBe('us')
+        expect(body.items).toHaveLength(1)
         return HttpResponse.json({
-          shipping_options: [
+          groups: [
             {
-              id: 'ship_1',
-              name: 'Express',
-              amount: 1000,
-              currency_code: 'usd',
-              price_type: 'flat',
-              is_default: true,
-              type: null,
+              profile_id: 'sp_1',
+              profile_label: 'Estándar',
+              products: ['variant_1'],
+              items: [
+                {
+                  variant_id: 'variant_1',
+                  quantity: 1,
+                  product_title: 'Product',
+                  variant_title: 'Default',
+                },
+              ],
+              options: [
+                {
+                  id: 'so_1',
+                  name: 'Estándar',
+                  amount: 500,
+                  currency_code: 'usd',
+                  price_type: 'flat',
+                  is_default: true,
+                  shipping_profile_id: 'sp_1',
+                  stock_location_id: 'sloc_1',
+                  type: null,
+                },
+              ],
             },
           ],
           count: 1,
@@ -614,30 +633,60 @@ describe('DropshipperClient.getOrderShippingOptions', () => {
       }),
     )
 
-    const result = await client().getOrderShippingOptions({ currency_code: 'usd', country_code: 'us' })
-    expect(result.shipping_options).toHaveLength(1)
-    expect(result.shipping_options[0].id).toBe('ship_1')
+    const result = await client().getOrderShippingOptions({
+      customer_id: 'cus_1',
+      currency_code: 'usd',
+      shipping_address: {
+        address_1: '123 Main St',
+        city: 'Miami',
+        province: 'FL',
+        country_code: 'us',
+      },
+      items: [{ variant_id: 'variant_1', quantity: 1 }],
+    })
+    expect(result.groups).toHaveLength(1)
+    expect(result.groups[0].profile_label).toBe('Estándar')
+    expect(result.groups[0].options[0].id).toBe('so_1')
+    expect(result.count).toBe(1)
   })
 
-  it('forwards province and city as query params', async () => {
+  it('forwards customer, address and items and returns groups', async () => {
     server.use(
-      http.get(`${BASE}/admin/thor/dropshipper/orders/shipping-options`, ({ request }) => {
+      http.post(`${BASE}/admin/thor/dropshipper/orders/shipping-options`, async ({ request }) => {
         requireBearerToken(request)
-        const url = new URL(request.url)
-        expect(url.searchParams.get('currency_code')).toBe('usd')
-        expect(url.searchParams.get('country_code')).toBe('cu')
-        expect(url.searchParams.get('province')).toBe('La Habana')
-        expect(url.searchParams.get('city')).toBe('Centro Habana')
+        const body = await request.json() as any
+        expect(body.currency_code).toBe('usd')
+        expect(body.customer_id).toBe('cus_1')
+        expect(body.shipping_address.province).toBe('La Habana')
+        expect(body.shipping_address.city).toBe('Centro Habana')
+        expect(body.items[0].variant_id).toBe('variant_1')
         return HttpResponse.json({
-          shipping_options: [
+          groups: [
             {
-              id: 'ship_1',
-              name: 'La Habana Express',
-              amount: 500,
-              currency_code: 'usd',
-              price_type: 'flat',
-              is_default: true,
-              type: null,
+              profile_id: 'sp_1',
+              profile_label: 'Estándar',
+              products: ['variant_1'],
+              items: [
+                {
+                  variant_id: 'variant_1',
+                  quantity: 1,
+                  product_title: 'Product',
+                  variant_title: 'Default',
+                },
+              ],
+              options: [
+                {
+                  id: 'so_1',
+                  name: 'La Habana Express',
+                  amount: 500,
+                  currency_code: 'usd',
+                  price_type: 'flat',
+                  is_default: true,
+                  shipping_profile_id: 'sp_1',
+                  stock_location_id: 'sloc_1',
+                  type: null,
+                },
+              ],
             },
           ],
           count: 1,
@@ -646,13 +695,18 @@ describe('DropshipperClient.getOrderShippingOptions', () => {
     )
 
     const result = await client().getOrderShippingOptions({
+      customer_id: 'cus_1',
       currency_code: 'usd',
-      country_code: 'cu',
-      province: 'La Habana',
-      city: 'Centro Habana',
+      shipping_address: {
+        address_1: 'Calle 1',
+        city: 'Centro Habana',
+        province: 'La Habana',
+        country_code: 'cu',
+      },
+      items: [{ variant_id: 'variant_1', quantity: 1 }],
     })
-    expect(result.shipping_options).toHaveLength(1)
-    expect(result.shipping_options[0].id).toBe('ship_1')
+    expect(result.groups).toHaveLength(1)
+    expect(result.groups[0].options[0].name).toBe('La Habana Express')
   })
 })
 

package/src/dropshipper.ts

@@ -36,8 +36,8 @@ import type {
   // Orders
   GetDropshipperOrdersOptions,
   GetDropshipperOrdersResponse,
-  GetDropshipperShippingOptionsParams,
-  GetDropshipperShippingOptionsResponse,
+ GetDropshipperShippingOptionsBody,
+ GetDropshipperShippingOptionsResponse,
   GetDropshipperOrderDetailResponse,
   ExtendedCreateDropshipperOrderBody,
   ExtendedCreateDropshipperOrderResponse,
@@ -801,23 +801,20 @@ export class DropshipperClient {
   }
 
   /**
-   * List shipping options for a manual dropshipper order.
+   * List shipping groups and their valid options for a manual dropshipper order.
    *
-   * `GET /admin/thor/dropshipper/orders/shipping-options`
+   * `POST /admin/thor/dropshipper/orders/shipping-options`
    */
   async getOrderShippingOptions(
-    params: GetDropshipperShippingOptionsParams,
+    body: GetDropshipperShippingOptionsBody,
   ): Promise<GetDropshipperShippingOptionsResponse> {
-    const qs = new URLSearchParams({
-      currency_code: params.currency_code.toLowerCase(),
-      ...(params.country_code ? { country_code: params.country_code.toLowerCase() } : {}),
-      ...(params.province ? { province: params.province } : {}),
-      ...(params.city ? { city: params.city } : {}),
-    });
-
     return this.request<GetDropshipperShippingOptionsResponse>(
-      'GET',
-      `/admin/thor/dropshipper/orders/shipping-options?${qs}`,
+      'POST',
+      '/admin/thor/dropshipper/orders/shipping-options',
+      {
+        ...body,
+        currency_code: body.currency_code.toLowerCase(),
+      },
     );
   }
 

package/src/recovery.ts

@@ -14,15 +14,28 @@
  *   - `POST /auth/user/emailpass/update`                    (confirm reset, consumes token)
  *   - `GET  /store/dropshipper/applications/activate/verify`(verify activation token, no consume)
  *   - `POST /store/dropshipper/applications/activate`       (confirm activation, consumes token)
+ *   - `POST /public/dropshipper/applications`               (submit application, no auth)
  *
  * Confirm methods follow the two-phase contract: verify (no consume) first,
  * then confirm (atomic consume). A re-verify after a failed confirm maps the
  * TOCTOU state (used/expired/revoked) into `RecoveryConfirmResult.status`.
+ *
+ * `submitApplication` returns a discriminated `SubmitApplicationResult` instead
+ * of throwing on 400/409/429 so the caller can surface the backend's structured
+ * payload (existing application on 409, retry window on 429). Network/5xx
+ * errors are re-thrown as `ProviderAPIError`.
  */
 
-import type { TokenVerifyResult, RecoveryConfirmResult } from '@thorprovider/types';
+import type {
+  SubmitApplicationBody,
+  SubmitApplicationConflictApplication,
+  SubmitApplicationResponse,
+  SubmitApplicationResult,
+  TokenVerifyResult,
+  RecoveryConfirmResult,
+} from '@thorprovider/types';
 import { createLogger, ProviderAPIError } from '@thorprovider/adapters';
-import { fetchBackendWithResilience } from './request-resilience';
+import { fetchBackendWithResilience, type RetryConfig } from './request-resilience';
 
 type FetchMethod = 'GET' | 'POST';
 
@@ -66,7 +79,12 @@ export class RecoveryClient {
   // Private — HTTP helper
   // -------------------------------------------------------------------------
 
-  private async request<T>(method: FetchMethod, path: string, body?: unknown): Promise<T> {
+  private async request<T>(
+    method: FetchMethod,
+    path: string,
+    body?: unknown,
+    retryConfig?: RetryConfig,
+  ): Promise<T> {
     const url = `${this.baseUrl}${path}`;
     this.logger.debug(`[recovery] ${method} ${path}`);
 
@@ -82,7 +100,7 @@ export class RecoveryClient {
 
     let response: Response;
     try {
-      response = await fetchBackendWithResilience(url, init);
+      response = await fetchBackendWithResilience(url, init, retryConfig);
     } catch (networkError: any) {
       throw new ProviderAPIError(
         `[recovery] Network error on ${method} ${path}: ${networkError.message}`,
@@ -93,9 +111,11 @@ export class RecoveryClient {
 
     if (!response.ok) {
       let message = `HTTP ${response.status}`;
+      let details: Record<string, unknown> | undefined;
       try {
         const json = await response.json();
         message = json?.message ?? message;
+        details = json && typeof json === 'object' ? (json as Record<string, unknown>) : undefined;
       } catch {
         // ignore parse errors
       }
@@ -103,6 +123,7 @@ export class RecoveryClient {
         `[recovery] ${method} ${path} failed: ${message}`,
         `RECOVERY_API_${response.status}`,
         response.status,
+        details,
       );
     }
 
@@ -244,4 +265,64 @@ export class RecoveryClient {
       }
     }
   }
+
+  // -------------------------------------------------------------------------
+  // Dropshipper application submission
+  // -------------------------------------------------------------------------
+
+  /**
+   * Envía una solicitud de acceso dropshipper al endpoint público.
+   *
+   * `POST /public/dropshipper/applications`
+   *
+   * No requiere autenticación. Devuelve un resultado discriminado:
+   * - `{ ok: true }` → 201, solicitud creada (`application.number`).
+   * - `{ ok: false, reason: 'conflict' }` → 409, email ya registrado; la
+   *   solicitud existente incluye `status_label`/`reason` para la UI.
+   * - `{ ok: false, reason: 'rate_limited' }` → 429, se respetó el límite del
+   *   backend; `retryAfterSeconds` indica cuándo reintentar.
+   * - `{ ok: false, reason: 'invalid_data' }` → 400, validación del backend.
+   *
+   * Los errores de red/5xx se re-lanzan como `ProviderAPIError` para que el
+   * llamador los categorice (p. ej. con `parseError`). El 429 no se reintenta
+   * (`retryableStatusCodes` sin 429) para que el caller reciba de inmediato el
+   * `retry_after_seconds` del backend y pueda bloquear el envío.
+   */
+  async submitApplication(body: SubmitApplicationBody): Promise<SubmitApplicationResult> {
+    try {
+      const response = await this.request<SubmitApplicationResponse>(
+        'POST',
+        '/public/dropshipper/applications',
+        body,
+        { retryableStatusCodes: [408, 500, 502, 503, 504] },
+      );
+      return { ok: true, application: response.application };
+    } catch (error) {
+      if (error instanceof ProviderAPIError) {
+        const details = error.details ?? {};
+        if (error.status === 409 && details.application) {
+          return {
+            ok: false,
+            reason: 'conflict',
+            application: details.application as SubmitApplicationConflictApplication,
+          };
+        }
+        if (error.status === 429 && typeof details.retry_after_seconds === 'number') {
+          return {
+            ok: false,
+            reason: 'rate_limited',
+            retryAfterSeconds: details.retry_after_seconds,
+          };
+        }
+        if (error.status === 400) {
+          return {
+            ok: false,
+            reason: 'invalid_data',
+            fields: details.fields as Record<string, string[]> | undefined,
+          };
+        }
+      }
+      throw error;
+    }
+  }
 }

package/src/request-resilience.ts

@@ -1,6 +1,6 @@
 import { ProviderAPIError, backendCircuitBreaker } from '@thorprovider/adapters'
 
-type RetryConfig = {
+export type RetryConfig = {
   maxRetries?: number
   initialDelayMs?: number
   backoffMultiplier?: number