Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Bootstrap `@spree/admin-sdk` release CI

Damian Legawiec06a8a52d784a
diff --git a/.github/workflows/packages.yml b/.github/workflows/packages.yml
index 29b1043f4a..a8c5742700 100644
--- a/.github/workflows/packages.yml
+++ b/.github/workflows/packages.yml
@@ -129,6 +129,64 @@ jobs:
if: steps.check.outputs.published == 'false'
run: pnpm turbo build --filter=@spree/sdk && npm publish --provenance --access public
+ release-admin-sdk:
+ name: "Admin SDK - Release"
+ needs: check
+ if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ pull-requests: write
+ id-token: write
+ defaults:
+ run:
+ working-directory: packages/admin-sdk
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: pnpm/action-setup@v4
+
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 20
+ cache: pnpm
+ registry-url: https://registry.npmjs.org
+
+ - run: pnpm install --frozen-lockfile
+ working-directory: .
+
+ - name: Upgrade npm for Trusted Publishing support
+ run: npm install -g npm@latest
+ working-directory: .
+
+ - name: Check if version is published
+ id: check
+ run: |
+ PACKAGE_VERSION=$(node -p "require('./package.json').version")
+ if npm view @spree/admin-sdk@$PACKAGE_VERSION version 2>/dev/null; then
+ echo "published=true" >> $GITHUB_OUTPUT
+ else
+ echo "published=false" >> $GITHUB_OUTPUT
+ fi
+
+ - name: Determine npm tag
+ id: tag
+ run: |
+ PACKAGE_VERSION=$(node -p "require('./package.json').version")
+ # Pre-1.0 / Developer Preview releases ship under the `next` tag so
+ # `npm install @spree/admin-sdk` doesn't pick them up as `latest`.
+ if echo "$PACKAGE_VERSION" | grep -qE '^0\.'; then
+ echo "tag=next" >> $GITHUB_OUTPUT
+ elif echo "$PACKAGE_VERSION" | grep -qE '[-]'; then
+ echo "tag=beta" >> $GITHUB_OUTPUT
+ else
+ echo "tag=latest" >> $GITHUB_OUTPUT
+ fi
+
+ - name: Build and Publish
+ if: steps.check.outputs.published == 'false'
+ run: pnpm turbo build --filter=@spree/admin-sdk && npm publish --provenance --access public --tag ${{ steps.tag.outputs.tag }}
+
release-cli:
name: "CLI - Release"
needs: check
diff --git a/packages/admin-sdk/.changeset/config.json b/packages/admin-sdk/.changeset/config.json
new file mode 100644
index 0000000000..95ea990266
--- /dev/null
+++ b/packages/admin-sdk/.changeset/config.json
@@ -0,0 +1,14 @@
+{
+ "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
+ "changelog": [
+ "@changesets/changelog-github",
+ { "repo": "spree/spree" }
+ ],
+ "commit": false,
+ "fixed": [],
+ "linked": [],
+ "access": "public",
+ "baseBranch": "main",
+ "updateInternalDependencies": "patch",
+ "ignore": []
+}
diff --git a/packages/admin-sdk/README.md b/packages/admin-sdk/README.md
new file mode 100644
index 0000000000..1559dc0fd4
--- /dev/null
+++ b/packages/admin-sdk/README.md
@@ -0,0 +1,182 @@
+# @spree/admin-sdk
+
+Official TypeScript SDK for the **Spree Commerce Admin API** — manage products, orders, customers, fulfillments, payments, and store configuration from server-to-server integrations or admin tooling.
+
+> **Developer Preview.** The Admin API is in active development and may change between minor versions. Pin to a specific version of `@spree/admin-sdk` in production and review the [changelog](./CHANGELOG.md) before upgrading.
+
+## Installation
+
+```bash
+npm install @spree/admin-sdk
+# or
+yarn add @spree/admin-sdk
+# or
+pnpm add @spree/admin-sdk
+```
+
+## Quick start
+
+```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+
+// List orders
+const { data: orders, meta } = await client.orders.list({
+ status_eq: 'complete',
+ sort: '-completed_at',
+ limit: 25,
+})
+
+// Create an order in one shot
+const order = await client.orders.create({
+ email: '[email protected]',
+ currency: 'USD',
+ items: [{ variant_id: 'variant_xxx', quantity: 1 }],
+ shipping_address: {
+ first_name: 'Jane',
+ last_name: 'Doe',
+ address1: '350 Fifth Avenue',
+ city: 'New York',
+ postal_code: '10118',
+ country_iso: 'US',
+ state_abbr: 'NY',
+ phone: '+1 212 555 1234',
+ },
+})
+
+// Manage a customer
+const customer = await client.customers.create({
+ email: '[email protected]',
+ first_name: 'Jane',
+ last_name: 'Doe',
+ tags: ['wholesale'],
+})
+
+await client.customers.addresses.create(customer.id, {
+ first_name: 'Jane',
+ last_name: 'Doe',
+ address1: '350 Fifth Avenue',
+ city: 'New York',
+ postal_code: '10118',
+ country_iso: 'US',
+ state_abbr: 'NY',
+ phone: '+1 212 555 1234',
+ is_default_shipping: true,
+})
+```
+
+## Authentication
+
+The Admin API supports two authentication methods.
+
+### Secret API key (server-to-server)
+
+Use a **secret API key** (`sk_…`) for backend integrations. Each key carries a list of [scopes](https://spreecommerce.org/docs/api-reference/admin-api/authentication#permissions) granted at creation time. Never embed secret keys in client-side code, mobile apps, or public repositories.
+
+```typescript
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ secretKey: 'sk_xxx',
+})
+```
+
+### JWT bearer token (admin SPA)
+
+Authenticate as an admin user and use the returned JWT for subsequent requests. JWT-authenticated requests use [CanCanCan abilities](https://github.com/CanCanCommunity/cancancan) instead of scopes.
+
+```typescript
+const client = createAdminClient({
+ baseUrl: 'https://store.example.com',
+ jwtToken: '<jwt>',
+})
+
+// Or login interactively:
+const tempClient = createAdminClient({ baseUrl, secretKey })
+const { token, refresh_token, user } = await tempClient.auth.login({
+ email: '[email protected]',
+ password: 'password123',
+})
+
+const adminClient = createAdminClient({ baseUrl, jwtToken: token })
+adminClient.onUnauthorized(async () => {
+ const { token: fresh } = await tempClient.auth.refresh({ token: refresh_token })
+ adminClient.setToken(fresh)
+ return true
+})
+```
+
+## Resource clients
+
+Top-level resources:
+
+| Client | Endpoints |
+|---|---|
+| `client.orders` | List, get, create, update, delete, complete, cancel, approve, resume, resend confirmation. Nested: `items`, `payments`, `fulfillments`, `refunds`, `giftCards`, `storeCredits`, `adjustments`. |
+| `client.customers` | List, get, create, update, delete. Nested: `addresses`, `creditCards`, `storeCredits`. |
+| `client.products` | List, get, create, update, delete. Nested: `media`, `variants` (which also has `media`). |
+| `client.variants` | Top-level variant search across products. |
+| `client.optionTypes` | CRUD on option types and values. |
+| `client.categories` | List and read categories. |
+| `client.paymentMethods` | List and read configured payment methods. |
+| `client.taxCategories` | List and read tax categories. |
+| `client.countries` | List and read countries (for address dropdowns). |
+| `client.tags` | Autocomplete tag names per taggable type. |
+| `client.dashboard` | Sales analytics. |
+| `client.store` | Store profile. |
+| `client.me` | Current admin user + permissions. |
+| `client.auth` | Login, refresh. |
+| `client.directUploads` | Pre-signed Active Storage uploads (used by media flows). |
+
+## Querying
+
+Collection endpoints support [Ransack](https://activerecord-hackery.github.io/ransack/) filters via flat parameters:
+
+```typescript
+const orders = await client.orders.list({
+ status_eq: 'complete',
+ total_gteq: 100,
+ email_cont: '@example.com',
+ user_id_eq: 'cus_xxx', // resource IDs work directly
+ sort: '-completed_at',
+ page: 2,
+ limit: 50,
+ expand: ['items', 'customer'],
+})
+```
+
+The SDK wraps filter keys in `q[…]` automatically.
+
+## Error handling
+
+Every non-2xx response throws a `SpreeError`:
+
+```typescript
+import { SpreeError } from '@spree/admin-sdk'
+
+try {
+ await client.orders.update(orderId, { email })
+} catch (err) {
+ if (err instanceof SpreeError) {
+ console.log(err.code) // e.g. 'cart_already_updated'
+ console.log(err.status) // e.g. 409
+ console.log(err.details) // optional structured context
+ }
+}
+```
+
+When a request fails because the API key lacks the required scope, the error has `code: 'access_denied'` and `details.required_scope` carries the missing scope name.
+
+## Documentation
+
+- **Full API reference:** [spreecommerce.org/docs/api-reference/admin-api](https://spreecommerce.org/docs/api-reference/admin-api/introduction)
+- **Authentication & scopes:** [spreecommerce.org/docs/api-reference/admin-api/authentication](https://spreecommerce.org/docs/api-reference/admin-api/authentication)
+- **Errors:** [spreecommerce.org/docs/api-reference/admin-api/errors](https://spreecommerce.org/docs/api-reference/admin-api/errors)
+- **Querying:** [spreecommerce.org/docs/api-reference/admin-api/querying](https://spreecommerce.org/docs/api-reference/admin-api/querying)
+
+## License
+
+MIT © [Vendo Connect Inc.](https://vendoconnect.com)
diff --git a/packages/admin-sdk/package.json b/packages/admin-sdk/package.json
index bca0fd5547..4ae1e869fa 100644
--- a/packages/admin-sdk/package.json
+++ b/packages/admin-sdk/package.json
@@ -1,7 +1,6 @@
{
"name": "@spree/admin-sdk",
"version": "0.1.0",
- "private": true,
"description": "Official TypeScript SDK for Spree Commerce Admin API",
"type": "module",
"main": "./dist/index.cjs",
@@ -66,12 +65,10 @@
"bugs": {
"url": "https://github.com/spree/spree/issues"
},
- "dependencies": {
- "@spree/sdk-core": "workspace:*"
- },
"devDependencies": {
"@changesets/changelog-github": "^0.6.0",
"@changesets/cli": "^2.30.0",
+ "@spree/sdk-core": "workspace:*",
"@types/node": "^25.5.0",
"@vitest/coverage-v8": "^4.1.2",
"tsup": "^8.0.0",
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index 02f4bfe814..29d3a2297d 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -69,7 +69,7 @@ export interface MeResponse {
};
permissions: PermissionRule[];
}
-import type { Store, Product, Order, Media, Category, TaxCategory, Country, Variant, PaymentMethod, Customer, CreditCard, Payment, Address, StoreCredit } from './types';
+import type { Store, Product, Order, Media, Category, TaxCategory, Country, Variant, PaymentMethod, Customer, CreditCard, Payment, Address, StoreCredit, LineItem, Fulfillment, Refund, Adjustment, OptionType } from './types';
import type {
StoreUpdateParams,
ProductUpdateParams,
@@ -91,6 +91,10 @@ import type {
LineItemCreateParams,
LineItemUpdateParams,
FulfillmentUpdateParams,
+ VariantCreateParams,
+ VariantUpdateParams,
+ OptionTypeCreateParams,
+ OptionTypeUpdateParams,
DirectUploadCreateParams,
} from './params';
@@ -187,6 +191,46 @@ export class AdminClient {
delete: (productId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/products/${productId}/media/${id}`, options),
},
+
+ variants: {
+ list: (productId: string, params?: ListParams & Record<string, unknown>, options?: RequestOptions): Promise<PaginatedResponse<Variant>> =>
+ this.request<PaginatedResponse<Variant>>('GET', `/products/${productId}/variants`, {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (productId: string, id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Variant> =>
+ this.request<Variant>('GET', `/products/${productId}/variants/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ create: (productId: string, params: VariantCreateParams, options?: RequestOptions): Promise<Variant> =>
+ this.request<Variant>('POST', `/products/${productId}/variants`, { ...options, body: params }),
+
+ update: (productId: string, id: string, params: VariantUpdateParams, options?: RequestOptions): Promise<Variant> =>
+ this.request<Variant>('PATCH', `/products/${productId}/variants/${id}`, { ...options, body: params }),
+
+ delete: (productId: string, id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/products/${productId}/variants/${id}`, options),
+
+ media: {
+ list: (productId: string, variantId: string, params?: ListParams & Record<string, unknown>, options?: RequestOptions): Promise<PaginatedResponse<Media>> =>
+ this.request<PaginatedResponse<Media>>('GET', `/products/${productId}/variants/${variantId}/media`, {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ create: (productId: string, variantId: string, params: MediaCreateParams, options?: RequestOptions): Promise<Media> =>
+ this.request<Media>('POST', `/products/${productId}/variants/${variantId}/media`, { ...options, body: params }),
+
+ update: (productId: string, variantId: string, id: string, params: MediaUpdateParams, options?: RequestOptions): Promise<Media> =>
+ this.request<Media>('PATCH', `/products/${productId}/variants/${variantId}/media/${id}`, { ...options, body: params }),
+
+ delete: (productId: string, variantId: string, id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/products/${productId}/variants/${variantId}/media/${id}`, options),
+ },
+ },
};
// ============================================
@@ -247,25 +291,55 @@ export class AdminClient {
},
items: {
- create: (orderId: string, params: LineItemCreateParams, options?: RequestOptions): Promise<unknown> =>
- this.request('POST', `/orders/${orderId}/items`, { ...options, body: params }),
+ list: (orderId: string, params?: ListParams & Record<string, unknown>, options?: RequestOptions): Promise<PaginatedResponse<LineItem>> =>
+ this.request<PaginatedResponse<LineItem>>('GET', `/orders/${orderId}/items`, {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (orderId: string, id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<LineItem> =>
+ this.request<LineItem>('GET', `/orders/${orderId}/items/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
- update: (orderId: string, id: string, params: LineItemUpdateParams, options?: RequestOptions): Promise<unknown> =>
- this.request('PATCH', `/orders/${orderId}/items/${id}`, { ...options, body: params }),
+ create: (orderId: string, params: LineItemCreateParams, options?: RequestOptions): Promise<LineItem> =>
+ this.request<LineItem>('POST', `/orders/${orderId}/items`, { ...options, body: params }),
+
+ update: (orderId: string, id: string, params: LineItemUpdateParams, options?: RequestOptions): Promise<LineItem> =>
+ this.request<LineItem>('PATCH', `/orders/${orderId}/items/${id}`, { ...options, body: params }),
delete: (orderId: string, id: string, options?: RequestOptions): Promise<void> =>
this.request<void>('DELETE', `/orders/${orderId}/items/${id}`, options),
},
fulfillments: {
- update: (orderId: string, id: string, params: FulfillmentUpdateParams, options?: RequestOptions): Promise<unknown> =>
- this.request('PATCH', `/orders/${orderId}/fulfillments/${id}`, { ...options, body: params }),
+ list: (orderId: string, params?: ListParams & Record<string, unknown>, options?: RequestOptions): Promise<PaginatedResponse<Fulfillment>> =>
+ this.request<PaginatedResponse<Fulfillment>>('GET', `/orders/${orderId}/fulfillments`, {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (orderId: string, id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Fulfillment> =>
+ this.request<Fulfillment>('GET', `/orders/${orderId}/fulfillments/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
- fulfill: (orderId: string, id: string, options?: RequestOptions): Promise<unknown> =>
- this.request('PATCH', `/orders/${orderId}/fulfillments/${id}/fulfill`, options),
+ update: (orderId: string, id: string, params: FulfillmentUpdateParams, options?: RequestOptions): Promise<Fulfillment> =>
+ this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}`, { ...options, body: params }),
- cancel: (orderId: string, id: string, options?: RequestOptions): Promise<unknown> =>
- this.request('PATCH', `/orders/${orderId}/fulfillments/${id}/cancel`, options),
+ fulfill: (orderId: string, id: string, options?: RequestOptions): Promise<Fulfillment> =>
+ this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/fulfill`, options),
+
+ cancel: (orderId: string, id: string, options?: RequestOptions): Promise<Fulfillment> =>
+ this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/cancel`, options),
+
+ resume: (orderId: string, id: string, options?: RequestOptions): Promise<Fulfillment> =>
+ this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/resume`, options),
+
+ split: (orderId: string, id: string, params: { quantity: number; line_item_id?: string }, options?: RequestOptions): Promise<Fulfillment> =>
+ this.request<Fulfillment>('PATCH', `/orders/${orderId}/fulfillments/${id}/split`, { ...options, body: params }),
},
payments: {
@@ -284,14 +358,63 @@ export class AdminClient {
create: (orderId: string, params: PaymentCreateParams, options?: RequestOptions): Promise<Payment> =>
this.request<Payment>('POST', `/orders/${orderId}/payments`, { ...options, body: params }),
- capture: (orderId: string, id: string, options?: RequestOptions): Promise<unknown> =>
- this.request('PATCH', `/orders/${orderId}/payments/${id}/capture`, options),
+ capture: (orderId: string, id: string, options?: RequestOptions): Promise<Payment> =>
+ this.request<Payment>('PATCH', `/orders/${orderId}/payments/${id}/capture`, options),
+
+ void: (orderId: string, id: string, options?: RequestOptions): Promise<Payment> =>
+ this.request<Payment>('PATCH', `/orders/${orderId}/payments/${id}/void`, options),
+ },
+
+ refunds: {
+ list: (orderId: string, params?: ListParams & Record<string, unknown>, options?: RequestOptions): Promise<PaginatedResponse<Refund>> =>
+ this.request<PaginatedResponse<Refund>>('GET', `/orders/${orderId}/refunds`, {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ create: (orderId: string, params: { payment_id: string; amount: number; reason_id?: string; refund_reason_id?: string }, options?: RequestOptions): Promise<Refund> =>
+ this.request<Refund>('POST', `/orders/${orderId}/refunds`, { ...options, body: params }),
+ },
+
+ adjustments: {
+ list: (orderId: string, params?: ListParams & Record<string, unknown>, options?: RequestOptions): Promise<PaginatedResponse<Adjustment>> =>
+ this.request<PaginatedResponse<Adjustment>>('GET', `/orders/${orderId}/adjustments`, {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
- void: (orderId: string, id: string, options?: RequestOptions): Promise<unknown> =>
- this.request('PATCH', `/orders/${orderId}/payments/${id}/void`, options),
+ get: (orderId: string, id: string, options?: RequestOptions): Promise<Adjustment> =>
+ this.request<Adjustment>('GET', `/orders/${orderId}/adjustments/${id}`, options),
},
};
+ // ============================================
+ // Option Types
+ // ============================================
+
+ readonly optionTypes = {
+ list: (params?: ListParams & Record<string, unknown>, options?: RequestOptions): Promise<PaginatedResponse<OptionType>> =>
+ this.request<PaginatedResponse<OptionType>>('GET', '/option_types', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<OptionType> =>
+ this.request<OptionType>('GET', `/option_types/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ create: (params: OptionTypeCreateParams, options?: RequestOptions): Promise<OptionType> =>
+ this.request<OptionType>('POST', '/option_types', { ...options, body: params }),
+
+ update: (id: string, params: OptionTypeUpdateParams, options?: RequestOptions): Promise<OptionType> =>
+ this.request<OptionType>('PATCH', `/option_types/${id}`, { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/option_types/${id}`, options),
+ };
+
// ============================================
// Payment Methods
// ============================================
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 0204ce16e6..7869b8f8e3 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -177,8 +177,8 @@ export interface CustomerAddressParams {
city?: string;
zipcode?: string;
postal_code?: string;
- country_id?: string | number;
- state_id?: string | number;
+ country_id?: string;
+ state_id?: string;
country_iso?: string;
state_abbr?: string;
phone?: string;
@@ -191,13 +191,13 @@ export interface CustomerAddressParams {
export interface CustomerStoreCreditCreateParams {
amount: number;
currency: string;
- category_id: string | number;
+ category_id: string;
memo?: string;
}
export interface CustomerStoreCreditUpdateParams {
amount?: number;
- category_id?: string | number;
+ category_id?: string;
memo?: string;
}
@@ -232,18 +232,7 @@ export interface ProductCreateParams {
tax_category_id?: string;
category_ids?: Array<string>;
tags?: Array<string>;
- variants?: Array<{
- sku?: string;
- price?: number;
- option_type?: string;
- option_value?: string;
- total_on_hand?: number;
- prices?: Array<{
- currency: string;
- amount: number;
- compare_at_amount?: number;
- }>;
- }>;
+ variants?: VariantCreateParams[];
}
export interface ProductUpdateParams {
@@ -255,18 +244,7 @@ export interface ProductUpdateParams {
tax_category_id?: string;
category_ids?: Array<string>;
tags?: Array<string>;
- variants?: Array<{
- sku?: string;
- price?: number;
- option_type?: string;
- option_value?: string;
- total_on_hand?: number;
- prices?: Array<{
- currency: string;
- amount: number;
- compare_at_amount?: number;
- }>;
- }>;
+ variants?: VariantUpdateParams[];
}
export interface CategoryCreateParams {
@@ -295,9 +273,25 @@ export interface CategoryUpdateParams {
sort_order?: string;
}
+export interface VariantOptionPair {
+ name: string;
+ value: string;
+}
+
+export interface VariantPrice {
+ currency: string;
+ amount: number;
+ compare_at_amount?: number;
+}
+
+export interface VariantStockItem {
+ stock_location_id: string;
+ count_on_hand: number;
+ backorderable?: boolean;
+}
+
export interface VariantCreateParams {
sku?: string;
- price?: number;
compare_at_price?: number;
cost_price?: number;
cost_currency?: string;
@@ -309,26 +303,15 @@ export interface VariantCreateParams {
dimensions_unit?: string;
track_inventory?: boolean;
tax_category_id?: string;
- option_type?: string;
- option_value?: string;
- total_on_hand?: number;
position?: number;
barcode?: string;
- prices?: Array<{
- currency: string;
- amount: number;
- compare_at_amount?: number;
- }>;
- stock_items?: Array<{
- stock_location_id?: string;
- count_on_hand?: number;
- backorderable?: boolean;
- }>;
+ options?: VariantOptionPair[];
+ prices?: VariantPrice[];
+ stock_items?: VariantStockItem[];
}
export interface VariantUpdateParams {
sku?: string;
- price?: number;
compare_at_price?: number;
cost_price?: number;
cost_currency?: string;
@@ -340,19 +323,9 @@ export interface VariantUpdateParams {
dimensions_unit?: string;
track_inventory?: boolean;
tax_category_id?: string;
- option_type?: string;
- option_value?: string;
- total_on_hand?: number;
position?: number;
barcode?: string;
- prices?: Array<{
- currency: string;
- amount: number;
- compare_at_amount?: number;
- }>;
- stock_items?: Array<{
- stock_location_id?: string;
- count_on_hand?: number;
- backorderable?: boolean;
- }>;
+ options?: VariantOptionPair[];
+ prices?: VariantPrice[];
+ stock_items?: VariantStockItem[];
}
diff --git a/packages/admin-sdk/tsup.config.ts b/packages/admin-sdk/tsup.config.ts
index 11764150a5..beb647703b 100644
--- a/packages/admin-sdk/tsup.config.ts
+++ b/packages/admin-sdk/tsup.config.ts
@@ -7,13 +7,14 @@ export default defineConfig({
'types/index': 'src/types/index.ts',
},
format: ['cjs', 'esm'],
- dts: true,
+ dts: { resolve: ['@spree/sdk-core'] },
splitting: false,
sourcemap: true,
clean: true,
treeshake: true,
minify: false,
- external: ['@spree/sdk-core'],
+ // sdk-core is workspace-private; inline it into the published bundle.
+ noExternal: ['@spree/sdk-core'],
esbuildOptions(options) {
options.alias = {
'@/types': path.resolve(import.meta.dirname, 'src/types/generated/index.ts'),
diff --git a/packages/sdk/ADMIN_SDK.md b/packages/sdk/ADMIN_SDK.md
deleted file mode 100644
index dba6d52cac..0000000000
--- a/packages/sdk/ADMIN_SDK.md
+++ /dev/null
@@ -1,1044 +0,0 @@
-# Spree Admin SDK
-
-The Admin SDK provides TypeScript methods for the Spree Admin API (`/api/v3/admin`). It is accessed via the `admin` property on a `SpreeClient` instance.
-
-## Setup
-
-```ts
-import { createSpreeClient } from '@spree/sdk'
-
-const client = createSpreeClient({
- baseUrl: 'https://mystore.com',
- secretKey: 'spree_sk_...',
-})
-```
-
-The `secretKey` is a secret API key created in the Spree admin. It is sent as `x-spree-api-key` on every request.
-
-## Common Patterns
-
-### Pagination
-
-All `list` methods return a `PaginatedResponse<T>`:
-
-```ts
-interface PaginatedResponse<T> {
- data: T[]
- meta: {
- page: number
- limit: number
- count: number
- pages: number
- from: number
- to: number
- in: number
- previous: number | null
- next: number | null
- }
-}
-```
-
-```ts
-const { data, meta } = await client.admin.products.list({ page: 2, limit: 25 })
-```
-
-### Sorting
-
-Pass a `sort` string. Prefix with `-` for descending:
-
-```ts
-await client.admin.orders.list({ sort: '-created_at' })
-```
-
-### Filtering (Ransack)
-
-Filter keys are automatically wrapped in `q[...]`:
-
-```ts
-await client.admin.orders.list({ state_eq: 'complete', completed_at_gte: '2024-01-01' })
-// Sends: q[state_eq]=complete&q[completed_at_gte]=2024-01-01
-```
-
-### Expanding Associations
-
-Pass `expand` as a string array. Supports dot notation for nested expand (max 4 levels):
-
-```ts
-await client.admin.products.get('prod_abc', { expand: ['variants', 'variants.images'] })
-```
-
-### Authenticated Requests
-
-Admin user operations require a Bearer token (from `admin.auth.login`) passed via `RequestOptions`:
-
-```ts
-const { token } = await client.admin.auth.login({
- email: '[email protected]',
- password: 'password',
-})
-
-await client.admin.orders.list({}, { token })
-```
-
-### Idempotency
-
-Mutating requests accept an `idempotencyKey` for safe retries:
-
-```ts
-await client.admin.orders.create(params, { token, idempotencyKey: 'unique-key-123' })
-```
-
-### Prefixed IDs
-
-All IDs in the Admin API use Stripe-style prefixed IDs (e.g., `prod_86Rf07xd4z`, `or_m3Rp9wXz`). Use these prefixed IDs in all method parameters.
-
----
-
-## Authentication
-
-### `admin.auth.login(credentials)`
-
-Login with email and password. Returns a JWT token for subsequent requests.
-
-```ts
-const { token, user } = await client.admin.auth.login({
- email: '[email protected]',
- password: 'password',
- provider: 'spree', // optional
-})
-```
-
-**Response:** `AdminAuthTokens`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `token` | `string` | JWT Bearer token |
-| `user.id` | `string` | Admin user prefixed ID |
-| `user.email` | `string` | Admin email |
-| `user.first_name` | `string \| null` | |
-| `user.last_name` | `string \| null` | |
-| `user.created_at` | `string` | |
-| `user.updated_at` | `string` | |
-
-### `admin.auth.refresh(options)`
-
-Refresh an access token. Requires a valid Bearer token.
-
-```ts
-const newTokens = await client.admin.auth.refresh({ token: currentToken })
-```
-
----
-
-## Products
-
-### `admin.products.list(params?, options?)`
-
-List products with pagination, sorting, and filtering.
-
-```ts
-const products = await client.admin.products.list({
- page: 1,
- limit: 25,
- sort: '-created_at',
- expand: ['variants'],
-}, { token })
-```
-
-### `admin.products.get(id, params?, options?)`
-
-Get a single product.
-
-```ts
-const product = await client.admin.products.get('prod_abc', {
- expand: ['variants', 'variants.images', 'taxons', 'option_types'],
-}, { token })
-```
-
-### `admin.products.create(params, options?)`
-
-Create a product.
-
-```ts
-const product = await client.admin.products.create({
- name: 'T-Shirt',
- price: 29.99,
- shipping_category_id: 'sc_abc',
- description: 'A comfortable t-shirt',
- status: 'draft',
- sku: 'TSHIRT-001',
- tax_category_id: 'tc_xyz',
- taxon_ids: ['taxon_abc', 'taxon_def'],
- tags: ['new', 'summer'],
- variants: [
- {
- sku: 'TSHIRT-S',
- price: 29.99,
- options: [
- { name: 'size', value: 'Small' },
- { name: 'color', value: 'Red' },
- ],
- prices: [
- { currency: 'USD', amount: 29.99 },
- { currency: 'EUR', amount: 27.99 },
- ],
- stock_items: [
- { location_id: 'loc_abc', quantity: 10, backorderable: true },
- ],
- },
- ],
-}, { token })
-```
-
-**Params:** `AdminProductCreateParams`
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | `string` | yes | |
-| `price` | `number` | yes | Default price (master variant) |
-| `shipping_category_id` | `string` | yes | Prefixed ID |
-| `description` | `string` | no | |
-| `slug` | `string` | no | Auto-generated from name if omitted |
-| `status` | `'draft' \| 'active' \| 'archived'` | no | Defaults to `draft` |
-| `sku` | `string` | no | Master variant SKU |
-| `tax_category_id` | `string` | no | Prefixed ID |
-| `taxon_ids` | `string[]` | no | Prefixed IDs |
-| `tags` | `string[]` | no | |
-| `variants` | `array` | no | Inline variant creation (see below) |
-
-**Inline variant params:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `sku` | `string` | |
-| `price` | `number` | |
-| `option_type` | `string` | Auto-created if needed |
-| `option_value` | `string` | Auto-created if needed |
-| `total_on_hand` | `number` | |
-| `prices` | `array` | `{ currency, amount, compare_at_amount? }` |
-
-### `admin.products.update(id, params, options?)`
-
-Update a product.
-
-```ts
-await client.admin.products.update('prod_abc', {
- name: 'Updated T-Shirt',
- status: 'active',
- tags: ['sale'],
-}, { token })
-```
-
-**Params:** `AdminProductUpdateParams` — same fields as create, all optional.
-
-### `admin.products.delete(id, options?)`
-
-Soft-delete a product.
-
-```ts
-await client.admin.products.delete('prod_abc', { token })
-```
-
-**Response:** `void` (204 No Content)
-
-### Response Type: `AdminProduct`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Prefixed ID (e.g., `prod_abc`) |
-| `name` | `string` | |
-| `description` | `string \| null` | |
-| `slug` | `string` | |
-| `status` | `string` | `draft`, `active`, or `archived` |
-| `variant_count` | `number` | Number of non-master variants |
-| `available_on` | `string \| null` | ISO 8601 timestamp |
-| `make_active_at` | `string \| null` | |
-| `discontinue_on` | `string \| null` | |
-| `purchasable` | `boolean` | |
-| `in_stock` | `boolean` | |
-| `backorderable` | `boolean` | |
-| `available` | `boolean` | |
-| `promotionable` | `boolean` | |
-| `default_variant_id` | `string` | Prefixed ID |
-| `thumbnail_url` | `string \| null` | |
-| `tags` | `string[]` | |
-| `price` | `AdminPrice` | Default variant price |
-| `original_price` | `AdminPrice \| null` | Compare-at price |
-| `shipping_category_id` | `string \| null` | |
-| `tax_category_id` | `string \| null` | |
-| `cost_price` | `string \| null` | |
-| `cost_currency` | `string \| null` | |
-| `meta_title` | `string \| null` | |
-| `meta_description` | `string \| null` | |
-| `meta_keywords` | `string \| null` | |
-| `deleted_at` | `string \| null` | |
-| `created_at` | `string` | |
-| `updated_at` | `string` | |
-| `variants?` | `AdminVariant[]` | Requires `expand: ['variants']` |
-| `default_variant?` | `AdminVariant` | Requires expand |
-| `master_variant?` | `AdminVariant` | Requires expand |
-| `images?` | `AdminImage[]` | Requires expand |
-| `option_types?` | `AdminOptionType[]` | Requires expand |
-| `taxons?` | `AdminTaxon[]` | Requires expand |
-| `metafields?` | `AdminMetafield[]` | Requires expand |
-| `shipping_category?` | `AdminShippingCategory` | Requires expand |
-| `tax_category?` | `AdminTaxCategory` | Requires expand |
-
----
-
-## Product Variants
-
-Nested under `admin.products.variants`.
-
-### `admin.products.variants.list(productId, params?, options?)`
-
-```ts
-const variants = await client.admin.products.variants.list('prod_abc', {
- expand: ['images', 'prices', 'stock_items'],
-}, { token })
-```
-
-### `admin.products.variants.get(productId, id, params?, options?)`
-
-```ts
-const variant = await client.admin.products.variants.get(
- 'prod_abc',
- 'variant_xyz',
- { expand: ['prices', 'stock_items'] },
- { token },
-)
-```
-
-### `admin.products.variants.create(productId, params, options?)`
-
-```ts
-const variant = await client.admin.products.variants.create('prod_abc', {
- sku: 'TSHIRT-L',
- price: 29.99,
- options: [{ name: 'Size', value: 'Large' }],
- track_inventory: true,
- prices: [
- { currency: 'USD', amount: 29.99, compare_at_amount: 39.99 },
- { currency: 'EUR', amount: 27.99 },
- ],
- stock_items: [
- { stock_location_id: 'sl_abc', count_on_hand: 50, backorderable: false },
- ],
-}, { token })
-```
-
-**Params:** `AdminVariantCreateParams`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `sku` | `string` | |
-| `price` | `number` | Default currency price |
-| `compare_at_price` | `number` | |
-| `cost_price` | `number` | |
-| `cost_currency` | `string` | |
-| `weight` | `number` | |
-| `height` | `number` | |
-| `width` | `number` | |
-| `depth` | `number` | |
-| `weight_unit` | `string` | `g`, `kg`, `lb`, `oz` |
-| `dimensions_unit` | `string` | `mm`, `cm`, `in`, `ft` |
-| `track_inventory` | `boolean` | |
-| `tax_category_id` | `string` | Prefixed ID |
-| `position` | `number` | |
-| `barcode` | `string` | |
-| `prices` | `array` | Multi-currency prices (upserted by currency) |
-| `stock_items` | `array` | Multi-location stock (upserted by location) |
-
-**Nested prices:**
-
-| Field | Type | Required |
-|-------|------|----------|
-| `currency` | `string` | yes |
-| `amount` | `number` | yes |
-| `compare_at_amount` | `number` | no |
-
-**Nested stock_items:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `stock_location_id` | `string` | Prefixed ID |
-| `count_on_hand` | `number` | |
-| `backorderable` | `boolean` | |
-
-### `admin.products.variants.update(productId, id, params, options?)`
-
-```ts
-await client.admin.products.variants.update('prod_abc', 'variant_xyz', {
- sku: 'TSHIRT-L-UPDATED',
- prices: [{ currency: 'USD', amount: 34.99 }],
-}, { token })
-```
-
-**Params:** `AdminVariantUpdateParams` — same fields as create, all optional.
-
-### `admin.products.variants.delete(productId, id, options?)`
-
-Soft-delete a variant.
-
-```ts
-await client.admin.products.variants.delete('prod_abc', 'variant_xyz', { token })
-```
-
-### Response Type: `AdminVariant`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Prefixed ID |
-| `product_id` | `string` | |
-| `sku` | `string \| null` | |
-| `is_master` | `boolean` | |
-| `options_text` | `string` | e.g., `"Size: Large, Color: Red"` |
-| `track_inventory` | `boolean` | |
-| `position` | `number` | |
-| `purchasable` | `boolean` | |
-| `in_stock` | `boolean` | |
-| `backorderable` | `boolean` | |
-| `weight` | `number \| null` | |
-| `height` | `number \| null` | |
-| `width` | `number \| null` | |
-| `depth` | `number \| null` | |
-| `weight_unit` | `string \| null` | |
-| `dimensions_unit` | `string \| null` | |
-| `barcode` | `string \| null` | |
-| `cost_price` | `string \| null` | |
-| `cost_currency` | `string \| null` | |
-| `tax_category_id` | `string \| null` | |
-| `total_on_hand` | `number \| null` | |
-| `thumbnail` | `string \| null` | Image URL |
-| `image_count` | `number` | |
-| `price` | `AdminPrice` | Default currency price |
-| `original_price` | `AdminPrice \| null` | Compare-at price |
-| `option_values` | `AdminOptionValue[]` | Always included |
-| `deleted_at` | `string \| null` | |
-| `discontinue_on` | `string \| null` | |
-| `created_at` | `string` | |
-| `updated_at` | `string` | |
-| `images?` | `AdminImage[]` | Requires expand |
-| `prices?` | `AdminPrice[]` | Requires expand |
-| `stock_items?` | `AdminStockItem[]` | Requires expand |
-| `product?` | `AdminProduct` | Requires expand |
-| `metafields?` | `AdminMetafield[]` | Requires expand |
-| `tax_category?` | `AdminTaxCategory` | Requires expand |
-
----
-
-## Product Assets
-
-Nested under `admin.products.assets`. Manages images and other media for the product's master variant.
-
-### `admin.products.assets.list(productId, params?, options?)`
-
-### `admin.products.assets.create(productId, params, options?)`
-
-```ts
-await client.admin.products.assets.create('prod_abc', {
- url: 'https://example.com/image.jpg',
- alt: 'Product front view',
- position: 1,
- type: 'Spree::Image',
-}, { token })
-```
-
-**Params:** `AdminAssetCreateParams`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `url` | `string` | URL of the image |
-| `alt` | `string` | Alt text |
-| `position` | `number` | Sort order |
-| `type` | `string` | Asset type (e.g., `Spree::Image`) |
-
-### `admin.products.assets.update(productId, id, params, options?)`
-
-### `admin.products.assets.delete(productId, id, options?)`
-
----
-
-## Variant Assets
-
-Nested under `admin.products.variants.assets`. Same interface as product assets, scoped to a specific variant.
-
-### `admin.products.variants.assets.list(productId, variantId, params?, options?)`
-
-### `admin.products.variants.assets.create(productId, variantId, params, options?)`
-
-### `admin.products.variants.assets.update(productId, variantId, id, params, options?)`
-
-### `admin.products.variants.assets.delete(productId, variantId, id, options?)`
-
----
-
-## Option Types
-
-### `admin.optionTypes.list(params?, options?)`
-
-```ts
-const optionTypes = await client.admin.optionTypes.list({}, { token })
-```
-
-### `admin.optionTypes.get(id, params?, options?)`
-
-```ts
-const optionType = await client.admin.optionTypes.get('ot_abc', {
- expand: ['metafields'],
-}, { token })
-```
-
-### `admin.optionTypes.create(params, options?)`
-
-```ts
-const optionType = await client.admin.optionTypes.create({
- name: 'size',
- presentation: 'Size',
- position: 1,
- filterable: true,
- option_values: [
- { name: 'small', presentation: 'S', position: 1 },
- { name: 'medium', presentation: 'M', position: 2 },
- { name: 'large', presentation: 'L', position: 3 },
- ],
-}, { token })
-```
-
-**Params:** `AdminOptionTypeCreateParams`
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | `string` | yes | Internal name |
-| `presentation` | `string` | yes | Display name |
-| `position` | `number` | no | Sort order |
-| `filterable` | `boolean` | no | Show in storefront filters |
-| `option_values` | `array` | no | Inline value creation |
-
-### `admin.optionTypes.update(id, params, options?)`
-
-```ts
-await client.admin.optionTypes.update('ot_abc', {
- presentation: 'Clothing Size',
- option_values: [
- { id: 'ov_abc', presentation: 'Small' }, // update existing
- { name: 'xl', presentation: 'XL', position: 4 }, // create new
- ],
-}, { token })
-```
-
-### `admin.optionTypes.delete(id, options?)`
-
-### Response Type: `AdminOptionType`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Prefixed ID |
-| `name` | `string` | |
-| `presentation` | `string` | |
-| `position` | `number` | |
-| `filterable` | `boolean` | |
-| `created_at` | `string` | |
-| `updated_at` | `string` | |
-| `option_values` | `AdminOptionValue[]` | Always included |
-| `metafields?` | `AdminMetafield[]` | Requires expand |
-
----
-
-## Orders
-
-### `admin.orders.list(params?, options?)`
-
-```ts
-const orders = await client.admin.orders.list({
- sort: '-completed_at',
- state_eq: 'complete',
- completed_at_gte: '2024-01-01',
- expand: ['line_items'],
-}, { token })
-```
-
-### `admin.orders.get(id, params?, options?)`
-
-```ts
-const order = await client.admin.orders.get('or_abc', {
- expand: ['adjustments', 'return_authorizations', 'reimbursements'],
-}, { token })
-```
-
-### `admin.orders.create(params, options?)`
-
-Create a draft order.
-
-```ts
-const order = await client.admin.orders.create({
- email: '[email protected]',
- user_id: 'user_abc',
- currency: 'USD',
- channel: 'admin',
- internal_note: 'Phone order',
-}, { token })
-```
-
-**Params:** `AdminOrderCreateParams`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `email` | `string` | Customer email |
-| `user_id` | `string` | Prefixed ID, link to existing user |
-| `currency` | `string` | Order currency |
-| `channel` | `string` | Sales channel |
-| `internal_note` | `string` | Internal staff note |
-
-### `admin.orders.update(id, params, options?)`
-
-```ts
-await client.admin.orders.update('or_abc', {
- email: '[email protected]',
- internal_note: 'Updated by admin',
- ship_address: {
- firstname: 'John',
- lastname: 'Doe',
- address1: '123 Main St',
- city: 'New York',
- zipcode: '10001',
- country_iso: 'US',
- state_abbr: 'NY',
- phone: '555-1234',
- },
- line_items: [
- { variant_id: 'variant_abc', quantity: 2 },
- ],
-}, { token })
-```
-
-**Params:** `AdminOrderUpdateParams`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `email` | `string` | |
-| `special_instructions` | `string` | Customer note |
-| `internal_note` | `string` | Staff note |
-| `channel` | `string` | |
-| `ship_address` | `object` | Shipping address |
-| `bill_address` | `object` | Billing address |
-| `line_items` | `array` | `{ variant_id, quantity }` |
-
-### `admin.orders.delete(id, options?)`
-
-Delete a draft order (only works on incomplete orders).
-
-### `admin.orders.cancel(id, params?, options?)`
-
-Cancel a completed order.
-
-```ts
-await client.admin.orders.cancel('or_abc', {}, { token })
-```
-
-### `admin.orders.approve(id, params?, options?)`
-
-Approve an order.
-
-### `admin.orders.resume(id, params?, options?)`
-
-Resume a canceled order.
-
-### `admin.orders.resendConfirmation(id, params?, options?)`
-
-Resend the order confirmation email.
-
-### Response Type: `AdminOrder`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Prefixed ID |
-| `number` | `string` | Order number (e.g., `R123456`) |
-| `state` | `string` | `cart`, `address`, `delivery`, `payment`, `confirm`, `complete` |
-| `email` | `string \| null` | |
-| `currency` | `string` | |
-| `item_count` | `number` | |
-| `item_total` | `string` | |
-| `ship_total` | `string` | |
-| `tax_total` | `string` | |
-| `total` | `string` | |
-| `payment_total` | `string` | |
-| `payment_state` | `string \| null` | `balance_due`, `paid`, `credit_owed`, etc. |
-| `shipment_state` | `string \| null` | `pending`, `ready`, `shipped`, `partial` |
-| `channel` | `string \| null` | |
-| `internal_note` | `string \| null` | |
-| `completed_at` | `string \| null` | |
-| `canceled_at` | `string \| null` | |
-| `approved_at` | `string \| null` | |
-| `created_at` | `string` | |
-| `updated_at` | `string` | |
-| `line_items` | `AdminLineItem[]` | Always included |
-| `shipments` | `AdminShipment[]` | Always included |
-| `payments` | `AdminPayment[]` | Always included |
-| `bill_address` | `StoreAddress \| null` | |
-| `ship_address` | `StoreAddress \| null` | |
-| `payment_methods` | `StorePaymentMethod[]` | |
-| `user?` | `AdminCustomer` | Requires expand |
-| `adjustments?` | `AdminAdjustment[]` | Requires expand |
-| `return_authorizations?` | `AdminReturnAuthorization[]` | Requires expand |
-| `reimbursements?` | `AdminReimbursement[]` | Requires expand |
-
----
-
-## Order Adjustments
-
-Nested under `admin.orders.adjustments`.
-
-### `admin.orders.adjustments.list(orderId, params?, options?)`
-
-### `admin.orders.adjustments.get(orderId, id, params?, options?)`
-
-### `admin.orders.adjustments.create(orderId, params, options?)`
-
-```ts
-await client.admin.orders.adjustments.create('or_abc', {
- amount: -5.00,
- label: 'Loyalty discount',
-}, { token })
-```
-
-**Params:** `AdminAdjustmentCreateParams`
-
-| Field | Type | Required |
-|-------|------|----------|
-| `amount` | `number` | yes |
-| `label` | `string` | yes |
-
-### `admin.orders.adjustments.update(orderId, id, params, options?)`
-
-**Params:** `AdminAdjustmentUpdateParams`
-
-| Field | Type |
-|-------|------|
-| `amount` | `number` |
-| `label` | `string` |
-| `eligible` | `boolean` |
-
-### `admin.orders.adjustments.delete(orderId, id, options?)`
-
----
-
-## Order Line Items
-
-Nested under `admin.orders.lineItems`.
-
-### `admin.orders.lineItems.list(orderId, params?, options?)`
-
-### `admin.orders.lineItems.get(orderId, id, params?, options?)`
-
-### `admin.orders.lineItems.create(orderId, params, options?)`
-
-```ts
-await client.admin.orders.lineItems.create('or_abc', {
- variant_id: 'variant_xyz',
- quantity: 2,
-}, { token })
-```
-
-**Params:** `AdminLineItemCreateParams`
-
-| Field | Type | Required |
-|-------|------|----------|
-| `variant_id` | `string` | yes |
-| `quantity` | `number` | no (defaults to 1) |
-
-### `admin.orders.lineItems.update(orderId, id, params, options?)`
-
-**Params:** `AdminLineItemUpdateParams` — `{ quantity?: number }`
-
-### `admin.orders.lineItems.delete(orderId, id, options?)`
-
----
-
-## Order Payments
-
-Nested under `admin.orders.payments`.
-
-### `admin.orders.payments.list(orderId, params?, options?)`
-
-### `admin.orders.payments.get(orderId, id, params?, options?)`
-
-### `admin.orders.payments.create(orderId, params, options?)`
-
-```ts
-await client.admin.orders.payments.create('or_abc', {
- payment_method_id: 'pm_xyz',
- amount: 49.99,
- source_id: 'cc_abc',
-}, { token })
-```
-
-**Params:** `AdminPaymentCreateParams`
-
-| Field | Type | Required |
-|-------|------|----------|
-| `payment_method_id` | `string` | yes |
-| `amount` | `number` | no |
-| `source_id` | `string` | no |
-
-### `admin.orders.payments.capture(orderId, id, params?, options?)`
-
-Capture an authorized payment.
-
-### `admin.orders.payments.void(orderId, id, params?, options?)`
-
-Void a pending payment.
-
----
-
-## Order Refunds
-
-Nested under `admin.orders.refunds`.
-
-### `admin.orders.refunds.list(orderId, params?, options?)`
-
-### `admin.orders.refunds.create(orderId, params, options?)`
-
-```ts
-await client.admin.orders.refunds.create('or_abc', {
- payment_id: 'pay_xyz',
- amount: 10.00,
- refund_reason_id: 'rr_abc',
-}, { token })
-```
-
-**Params:** `AdminRefundCreateParams`
-
-| Field | Type | Required |
-|-------|------|----------|
-| `payment_id` | `string` | yes |
-| `amount` | `number` | yes |
-| `refund_reason_id` | `string` | no |
-
----
-
-## Order Shipments
-
-Nested under `admin.orders.shipments`.
-
-### `admin.orders.shipments.list(orderId, params?, options?)`
-
-### `admin.orders.shipments.get(orderId, id, params?, options?)`
-
-### `admin.orders.shipments.update(orderId, id, params, options?)`
-
-```ts
-await client.admin.orders.shipments.update('or_abc', 'ship_xyz', {
- tracking: '1Z999AA10123456784',
- selected_shipping_rate_id: 'sr_abc',
-}, { token })
-```
-
-**Params:** `AdminShipmentUpdateParams`
-
-| Field | Type |
-|-------|------|
-| `tracking` | `string` |
-| `selected_shipping_rate_id` | `string` |
-
-### `admin.orders.shipments.ship(orderId, id, params?, options?)`
-
-Mark a shipment as shipped.
-
-### `admin.orders.shipments.cancel(orderId, id, params?, options?)`
-
-Cancel a shipment.
-
-### `admin.orders.shipments.resume(orderId, id, params?, options?)`
-
-Resume a canceled shipment.
-
-### `admin.orders.shipments.split(orderId, id, params?, options?)`
-
-Split a shipment.
-
----
-
-## Taxonomies
-
-### `admin.taxonomies.list(params?, options?)`
-
-```ts
-const taxonomies = await client.admin.taxonomies.list({
- expand: ['taxons', 'root'],
-}, { token })
-```
-
-### `admin.taxonomies.get(id, params?, options?)`
-
-### `admin.taxonomies.create(params, options?)`
-
-```ts
-const taxonomy = await client.admin.taxonomies.create({
- name: 'Categories',
- position: 1,
-}, { token })
-```
-
-**Params:** `AdminTaxonomyCreateParams`
-
-| Field | Type | Required |
-|-------|------|----------|
-| `name` | `string` | yes |
-| `position` | `number` | no |
-
-### `admin.taxonomies.update(id, params, options?)`
-
-### `admin.taxonomies.delete(id, options?)`
-
-### Response Type: `AdminTaxonomy`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Prefixed ID |
-| `name` | `string` | |
-| `position` | `number` | |
-| `store_id` | `string \| null` | |
-| `root_id` | `string \| null` | Root taxon ID |
-| `created_at` | `string` | |
-| `updated_at` | `string` | |
-| `root?` | `AdminTaxon` | Requires expand |
-| `taxons?` | `AdminTaxon[]` | Requires expand |
-| `metafields?` | `AdminMetafield[]` | Requires expand |
-
----
-
-## Taxonomy Taxons
-
-Nested under `admin.taxonomies.taxons`. Manages taxons within a specific taxonomy.
-
-### `admin.taxonomies.taxons.list(taxonomyId, params?, options?)`
-
-### `admin.taxonomies.taxons.get(taxonomyId, id, params?, options?)`
-
-### `admin.taxonomies.taxons.create(taxonomyId, params, options?)`
-
-```ts
-const taxon = await client.admin.taxonomies.taxons.create('taxonomy_abc', {
- name: 'T-Shirts',
- parent_id: 'taxon_root',
- position: 1,
- description: 'All t-shirt products',
- meta_title: 'T-Shirts',
- hide_from_nav: false,
-}, { token })
-```
-
-**Params:** `AdminTaxonCreateParams`
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | `string` | yes | |
-| `parent_id` | `string` | no | Prefixed ID of parent taxon |
-| `position` | `number` | no | |
-| `description` | `string` | no | |
-| `permalink` | `string` | no | Custom URL slug |
-| `meta_title` | `string` | no | |
-| `meta_description` | `string` | no | |
-| `meta_keywords` | `string` | no | |
-| `hide_from_nav` | `boolean` | no | |
-| `sort_order` | `string` | no | |
-
-### `admin.taxonomies.taxons.update(taxonomyId, id, params, options?)`
-
-### `admin.taxonomies.taxons.delete(taxonomyId, id, options?)`
-
----
-
-## Taxons (Flat)
-
-A flat endpoint for listing and retrieving taxons across all taxonomies.
-
-### `admin.taxons.list(params?, options?)`
-
-```ts
-const taxons = await client.admin.taxons.list({
- expand: ['taxonomy', 'children'],
-}, { token })
-```
-
-### `admin.taxons.get(id, params?, options?)`
-
-### Response Type: `AdminTaxon`
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Prefixed ID |
-| `name` | `string` | |
-| `permalink` | `string` | URL path |
-| `position` | `number` | |
-| `depth` | `number` | Nesting depth (0 = root) |
-| `parent_id` | `string \| null` | |
-| `taxonomy_id` | `string` | |
-| `description` | `string` | |
-| `description_html` | `string` | |
-| `image_url` | `string \| null` | |
-| `square_image_url` | `string \| null` | |
-| `children_count` | `number` | |
-| `is_root` | `boolean` | |
-| `is_child` | `boolean` | |
-| `is_leaf` | `boolean` | |
-| `hide_from_nav` | `boolean` | |
-| `sort_order` | `string` | |
-| `automatic` | `boolean` | Auto-matching rules |
-| `rules_match_policy` | `string` | |
-| `lft` | `number` | Nested set left |
-| `rgt` | `number` | Nested set right |
-| `meta_title` | `string \| null` | |
-| `meta_description` | `string \| null` | |
-| `meta_keywords` | `string \| null` | |
-| `created_at` | `string` | |
-| `updated_at` | `string` | |
-| `parent?` | `AdminTaxon` | Requires expand |
-| `children?` | `AdminTaxon[]` | Requires expand |
-| `ancestors?` | `AdminTaxon[]` | Requires expand |
-| `taxonomy?` | `AdminTaxonomy` | Requires expand |
-| `metafields?` | `AdminMetafield[]` | Requires expand |
-
----
-
-## Error Handling
-
-All methods throw `SpreeError` on failure:
-
-```ts
-import { SpreeError } from '@spree/sdk'
-
-try {
- await client.admin.products.get('prod_nonexistent', {}, { token })
-} catch (error) {
- if (error instanceof SpreeError) {
- console.log(error.code) // 'not_found'
- console.log(error.status) // 404
- console.log(error.message) // "Couldn't find Spree::Product..."
- console.log(error.details) // { field: ['message'] } for validation errors
- }
-}
-```
-
-### Error Response Shape
-
-```ts
-interface ErrorResponse {
- error: {
- code: string // 'not_found', 'validation_error', 'unauthorized', etc.
- message: string
- details?: Record<string, string[]> // field-level errors for 422s
- }
-}
-```
-
-Common error codes:
-
-| Code | Status | Description |
-|------|--------|-------------|
-| `unauthorized` | 401 | Missing or invalid API key / token |
-| `forbidden` | 403 | Insufficient permissions |
-| `not_found` | 404 | Resource not found |
-| `validation_error` | 422 | Invalid params (see `details` for fields) |
-| `conflict` | 409 | Idempotency key conflict |
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e39e681896..76d83c59d2 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -132,10 +132,6 @@ importers:
packages/admin-sdk:
- dependencies:
- '@spree/sdk-core':
- specifier: workspace:*
- version: link:../sdk-core
devDependencies:
'@changesets/changelog-github':
specifier: ^0.6.0
@@ -143,6 +139,9 @@ importers:
'@changesets/cli':
specifier: ^2.30.0
version: 2.30.0(@types/[email protected])
+ '@spree/sdk-core':
+ specifier: workspace:*
+ version: link:../sdk-core
'@types/node':
specifier: ^25.5.0
version: 25.5.2