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.

Sprint 3 SDK — tax categories writes, stock items, stock transfers, payment methods writes

Damian Legawiecdd5f34ae0e2b
diff --git a/packages/admin-sdk/.changeset/admin-sprint-3-writes.md b/packages/admin-sdk/.changeset/admin-sprint-3-writes.md
new file mode 100644
index 0000000000..65933204b3
--- /dev/null
+++ b/packages/admin-sdk/.changeset/admin-sprint-3-writes.md
@@ -0,0 +1,12 @@
+---
+'@spree/admin-sdk': minor
+---
+
+Sprint 3: utility CRUD writes for tax categories, stock items, stock transfers, and payment methods.
+
+- `client.taxCategories` gains `get / create / update / delete`. Backed by `/api/v3/admin/tax_categories`. The serializer now exposes `description` alongside `name`, `tax_code`, and `is_default`. Setting `is_default: true` on create or update auto-demotes the previous default.
+- `client.stockItems` is new with `list / get / update / delete`. Adjust `count_on_hand` and `backorderable` on existing variant/location pairings. Stock items are auto-created when a variant lands at a stock location, so there's no `create` here — use the variants and stock-locations endpoints for that flow. Filterable via Ransack on `count_on_hand`, `stock_location_id`, and `variant_id`.
+- `client.stockTransfers` is new with `list / get / create / delete`. Backed by `/api/v3/admin/stock_transfers`. The create body takes a `variants: [{ variant_id, quantity }]` array; pass `source_location_id` for a transfer between two locations or omit it to record an external vendor receive at the destination. The model fans the payload out across `stock_movements` and adjusts source/destination `count_on_hand` atomically.
+- `client.paymentMethods` gains `create / update / delete`. The create body requires `type` (the fully-qualified STI subclass, e.g. `'Spree::PaymentMethod::Check'`); unknown types return a 422 with `unknown_payment_method_type`. New payment methods are scoped to the current store automatically. The serializer now exposes `display_on` and `position` on top of the existing `name`, `description`, `type`, `active`, and `auto_capture`.
+
+Provider-specific configuration (Stripe API keys, PayPal credentials, etc.) is **not** part of this release — that lands with the universal preferences form in the next sprint.
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index a616b33a5b..2f8144818a 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -119,11 +119,17 @@ import type {
OrderCreateParams,
OrderUpdateParams,
PaymentCreateParams,
+ PaymentMethodCreateParams,
+ PaymentMethodUpdateParams,
ProductUpdateParams,
+ StockItemUpdateParams,
StockLocationCreateParams,
StockLocationUpdateParams,
+ StockTransferCreateParams,
StoreCreditApplyParams,
StoreUpdateParams,
+ TaxCategoryCreateParams,
+ TaxCategoryUpdateParams,
VariantCreateParams,
VariantUpdateParams,
} from './params'
@@ -150,7 +156,9 @@ import type {
Product,
Refund,
Role,
+ StockItem,
StockLocation,
+ StockTransfer,
Store,
StoreCredit,
StoreCreditCategory,
@@ -886,6 +894,19 @@ export class AdminClient {
...options,
params: getParams(params),
}),
+
+ create: (params: PaymentMethodCreateParams, options?: RequestOptions): Promise<PaymentMethod> =>
+ this.request<PaymentMethod>('POST', '/payment_methods', { ...options, body: params }),
+
+ update: (
+ id: string,
+ params: PaymentMethodUpdateParams,
+ options?: RequestOptions,
+ ): Promise<PaymentMethod> =>
+ this.request<PaymentMethod>('PATCH', `/payment_methods/${id}`, { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/payment_methods/${id}`, options),
}
// ============================================
@@ -1155,6 +1176,29 @@ export class AdminClient {
...options,
params: params ? transformListParams(params) : undefined,
}),
+
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<TaxCategory> =>
+ this.request<TaxCategory>('GET', `/tax_categories/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ create: (params: TaxCategoryCreateParams, options?: RequestOptions): Promise<TaxCategory> =>
+ this.request<TaxCategory>('POST', '/tax_categories', { ...options, body: params }),
+
+ update: (
+ id: string,
+ params: TaxCategoryUpdateParams,
+ options?: RequestOptions,
+ ): Promise<TaxCategory> =>
+ this.request<TaxCategory>('PATCH', `/tax_categories/${id}`, { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/tax_categories/${id}`, options),
}
// ============================================
@@ -1220,6 +1264,77 @@ export class AdminClient {
this.request<void>('DELETE', `/stock_locations/${id}`, options),
}
+ // ============================================
+ // Stock Items
+ // ============================================
+
+ readonly stockItems = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<StockItem>> =>
+ this.request<PaginatedResponse<StockItem>>('GET', '/stock_items', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<StockItem> =>
+ this.request<StockItem>('GET', `/stock_items/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ update: (
+ id: string,
+ params: StockItemUpdateParams,
+ options?: RequestOptions,
+ ): Promise<StockItem> =>
+ this.request<StockItem>('PATCH', `/stock_items/${id}`, { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/stock_items/${id}`, options),
+ }
+
+ // ============================================
+ // Stock Transfers
+ // ============================================
+
+ /**
+ * Inventory movement between stock locations, or external → location for
+ * receives. Pass `source_location_id` for transfers; omit it to record a
+ * vendor receive (external stock arriving at the destination).
+ */
+ readonly stockTransfers = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<StockTransfer>> =>
+ this.request<PaginatedResponse<StockTransfer>>('GET', '/stock_transfers', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<StockTransfer> =>
+ this.request<StockTransfer>('GET', `/stock_transfers/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ create: (params: StockTransferCreateParams, options?: RequestOptions): Promise<StockTransfer> =>
+ this.request<StockTransfer>('POST', '/stock_transfers', { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/stock_transfers/${id}`, options),
+ }
+
// ============================================
// Countries
// ============================================
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index b9dac6a696..834c410297 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -435,6 +435,57 @@ export interface StockLocationUpdateParams {
pickup_instructions?: string | null
}
+export interface StockItemUpdateParams {
+ count_on_hand?: number
+ backorderable?: boolean
+ metadata?: Record<string, unknown>
+}
+
+export interface StockTransferCreateParams {
+ /** Omit for a vendor receive (external stock arriving at the destination). */
+ source_location_id?: string
+ destination_location_id: string
+ reference?: string
+ variants: Array<{ variant_id: string; quantity: number }>
+}
+
+export interface TaxCategoryCreateParams {
+ name: string
+ tax_code?: string | null
+ description?: string | null
+ is_default?: boolean
+}
+
+export interface TaxCategoryUpdateParams {
+ name?: string
+ tax_code?: string | null
+ description?: string | null
+ is_default?: boolean
+}
+
+export interface PaymentMethodCreateParams {
+ /** Fully-qualified STI subclass name, e.g. 'Spree::PaymentMethod::Check'. */
+ type: string
+ name: string
+ description?: string | null
+ active?: boolean
+ /** 'front_end' | 'back_end' | 'both'. */
+ display_on?: string
+ auto_capture?: boolean | null
+ position?: number
+ metadata?: Record<string, unknown>
+}
+
+export interface PaymentMethodUpdateParams {
+ name?: string
+ description?: string | null
+ active?: boolean
+ display_on?: string
+ auto_capture?: boolean | null
+ position?: number
+ metadata?: Record<string, unknown>
+}
+
/**
* Built-in `Spree::Export` subclasses. The server validates `type` against
* the configured allowlist (`Spree::Export.available_types`); a plugin can
diff --git a/packages/admin-sdk/src/types/generated/PaymentMethod.ts b/packages/admin-sdk/src/types/generated/PaymentMethod.ts
index 3337f81a56..9025665278 100644
--- a/packages/admin-sdk/src/types/generated/PaymentMethod.ts
+++ b/packages/admin-sdk/src/types/generated/PaymentMethod.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 54dbf7d0a58f85679adeb642593391a6
+// Typelizer digest b453b4488d0380fda2421df64d183a9e
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -12,6 +12,8 @@ interface PaymentMethod {
metadata: Record<string, unknown>;
active: boolean;
auto_capture: boolean | null;
+ display_on: string;
+ position: number;
created_at: string;
updated_at: string;
}
diff --git a/packages/admin-sdk/src/types/generated/StockTransfer.ts b/packages/admin-sdk/src/types/generated/StockTransfer.ts
new file mode 100644
index 0000000000..8171d855d0
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/StockTransfer.ts
@@ -0,0 +1,19 @@
+// Typelizer digest 409e958482df1f2a172e9eb5b5aea12f
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {StockLocation} from '@/types'
+
+interface StockTransfer {
+ id: string;
+ number: string;
+ reference: string | null;
+ metadata: Record<string, unknown>;
+ created_at: string;
+ updated_at: string;
+ source_location_id: string | null;
+ destination_location_id: string | null;
+ source_location?: StockLocation;
+ destination_location?: StockLocation;
+}
+
+export default StockTransfer;
diff --git a/packages/admin-sdk/src/types/generated/TaxCategory.ts b/packages/admin-sdk/src/types/generated/TaxCategory.ts
index a17b0ac48f..2d351119d1 100644
--- a/packages/admin-sdk/src/types/generated/TaxCategory.ts
+++ b/packages/admin-sdk/src/types/generated/TaxCategory.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 94bb83364f75605bf0fdf1fc9e79367c
+// Typelizer digest 89ce5af6a81dc8aa6b5248d4ee28429e
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -6,6 +6,7 @@ interface TaxCategory {
id: string;
name: string;
tax_code: string | null;
+ description: string | null;
is_default: boolean;
created_at: string;
updated_at: string;
diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.ts
index 73176f42f6..53c25a0beb 100644
--- a/packages/admin-sdk/src/types/generated/index.ts
+++ b/packages/admin-sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 2ae0ae57d1bef733bca734ae9e2e6ac4
+// Typelizer digest fbfb43b4c1c1d460f556e07ba7ffc38e
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -39,6 +39,7 @@ export type { default as Role } from './Role'
export type { default as State } from './State'
export type { default as StockItem } from './StockItem'
export type { default as StockLocation } from './StockLocation'
+export type { default as StockTransfer } from './StockTransfer'
export type { default as StoreCreditCategory } from './StoreCreditCategory'
export type { default as StoreCredit } from './StoreCredit'
export type { default as Store } from './Store'
diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.ts
index e298430a61..2e8cbb843d 100644
--- a/packages/admin-sdk/src/types/index.ts
+++ b/packages/admin-sdk/src/types/index.ts
@@ -47,6 +47,7 @@ export type { default as Role } from './generated/Role'
export type { default as State } from './generated/State'
export type { default as StockItem } from './generated/StockItem'
export type { default as StockLocation } from './generated/StockLocation'
+export type { default as StockTransfer } from './generated/StockTransfer'
export type { default as Store } from './generated/Store'
export type { default as StoreCredit } from './generated/StoreCredit'
export type { default as StoreCreditCategory } from './generated/StoreCreditCategory'
diff --git a/packages/admin-sdk/tsconfig.tsbuildinfo b/packages/admin-sdk/tsconfig.tsbuildinfo
index e5d0a57cce..af7b901d68 100644
--- a/packages/admin-sdk/tsconfig.tsbuildinfo
+++ b/packages/admin-sdk/tsconfig.tsbuildinfo
@@ -1 +1 @@
-{"root":["./src/admin-client.ts","./src/client.ts","./src/index.ts","./src/params.ts","./src/types/index.ts","./src/types/generated/address.ts","./src/types/generated/adjustment.ts","./src/types/generated/adminuser.ts","./src/types/generated/allowedorigin.ts","./src/types/generated/apikey.ts","./src/types/generated/category.ts","./src/types/generated/country.ts","./src/types/generated/creditcard.ts","./src/types/generated/customfield.ts","./src/types/generated/customfielddefinition.ts","./src/types/generated/customer.ts","./src/types/generated/deliverymethod.ts","./src/types/generated/deliveryrate.ts","./src/types/generated/digitallink.ts","./src/types/generated/discount.ts","./src/types/generated/export.ts","./src/types/generated/fulfillment.ts","./src/types/generated/giftcard.ts","./src/types/generated/invitation.ts","./src/types/generated/lineitem.ts","./src/types/generated/market.ts","./src/types/generated/media.ts","./src/types/generated/optiontype.ts","./src/types/generated/optionvalue.ts","./src/types/generated/order.ts","./src/types/generated/payment.ts","./src/types/generated/paymentmethod.ts","./src/types/generated/paymentsource.ts","./src/types/generated/price.ts","./src/types/generated/pricehistory.ts","./src/types/generated/product.ts","./src/types/generated/refund.ts","./src/types/generated/reimbursement.ts","./src/types/generated/returnauthorization.ts","./src/types/generated/role.ts","./src/types/generated/state.ts","./src/types/generated/stockitem.ts","./src/types/generated/stocklocation.ts","./src/types/generated/store.ts","./src/types/generated/storecredit.ts","./src/types/generated/storecreditcategory.ts","./src/types/generated/taxcategory.ts","./src/types/generated/variant.ts","./src/types/generated/index.ts"],"version":"6.0.3"}
\ No newline at end of file
+{"root":["./src/admin-client.ts","./src/client.ts","./src/index.ts","./src/params.ts","./src/types/index.ts","./src/types/generated/address.ts","./src/types/generated/adjustment.ts","./src/types/generated/adminuser.ts","./src/types/generated/allowedorigin.ts","./src/types/generated/apikey.ts","./src/types/generated/category.ts","./src/types/generated/country.ts","./src/types/generated/creditcard.ts","./src/types/generated/customfield.ts","./src/types/generated/customfielddefinition.ts","./src/types/generated/customer.ts","./src/types/generated/deliverymethod.ts","./src/types/generated/deliveryrate.ts","./src/types/generated/digitallink.ts","./src/types/generated/discount.ts","./src/types/generated/export.ts","./src/types/generated/fulfillment.ts","./src/types/generated/giftcard.ts","./src/types/generated/invitation.ts","./src/types/generated/lineitem.ts","./src/types/generated/market.ts","./src/types/generated/media.ts","./src/types/generated/optiontype.ts","./src/types/generated/optionvalue.ts","./src/types/generated/order.ts","./src/types/generated/payment.ts","./src/types/generated/paymentmethod.ts","./src/types/generated/paymentsource.ts","./src/types/generated/price.ts","./src/types/generated/pricehistory.ts","./src/types/generated/product.ts","./src/types/generated/refund.ts","./src/types/generated/reimbursement.ts","./src/types/generated/returnauthorization.ts","./src/types/generated/role.ts","./src/types/generated/state.ts","./src/types/generated/stockitem.ts","./src/types/generated/stocklocation.ts","./src/types/generated/stocktransfer.ts","./src/types/generated/store.ts","./src/types/generated/storecredit.ts","./src/types/generated/storecreditcategory.ts","./src/types/generated/taxcategory.ts","./src/types/generated/variant.ts","./src/types/generated/index.ts"],"version":"6.0.3"}
\ No newline at end of file