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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Sprint 4 SDK — promotion stack + universal preferences round-trip
Damian Legawiec2f64cdd353d3
diff --git a/packages/admin-sdk/.changeset/admin-sprint-4-promotions.md b/packages/admin-sdk/.changeset/admin-sprint-4-promotions.mdnew file mode 100644index 0000000000..b3f0f4e3b2--- /dev/null+++ b/packages/admin-sdk/.changeset/admin-sprint-4-promotions.md@@ -0,0 +1,19 @@+---+'@spree/admin-sdk': minor+---++Sprint 4: full admin promotion stack — promotions, actions, rules, and coupon codes.++- `client.promotions` is new with `list / get / create / update / delete`. Mirrors `Spree::Promotion`: `name`, `description`, `code`, `starts_at`, `expires_at`, `usage_limit`, `match_policy`, `kind` (`'coupon_code' | 'automatic'`), `multi_codes` + `number_of_codes` + `code_prefix` for batch coupon generation, `path`, `advertise`, `promotion_category_id`, and `store_ids`.++- `client.promotions.actions` (nested) handles the STI subclass pattern: `list / get / create / update / delete` on `/promotions/:id/promotion_actions`. The create body takes a `type` (the fully-qualified subclass like `'Spree::Promotion::Actions::FreeShipping'`) plus a `preferences: { ... }` hash that round-trips through the typed setters declared on the subclass.++- `client.promotions.rules` (nested) is the same shape for `Spree::PromotionRule` subclasses (Currency, Country, ItemTotal, Product, Taxon, etc.).++- `client.promotions.couponCodes` (nested) is read-only — `list / get`. Coupon codes are server-generated based on the promotion's `multi_codes` settings.++- `client.promotionActions.types()` and `client.promotionRules.types()` are top-level discovery endpoints. Each returns `{ data: ResourceTypeDefinition[] }` where each entry is `{ type, label, description, preference_schema }`. The `preference_schema` describes the configurable knobs for a given subclass — `[{ key, type, default }]` — so admin UIs can render generic configuration forms without hard-coding per-subclass field lists.++- `client.paymentMethods.create / update` now accept an optional `preferences` hash, matching the same round-trip pattern. The serializer payload also gains `preferences` (current values) and `preference_schema` (shape).++- New shared types: `PreferenceField`, `ResourceTypeDefinition`. The previously-shipped `PaymentMethodType` is now an alias of `ResourceTypeDefinition`.diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.tsindex 2c81e2c9a4..507717bdab 100644--- a/packages/admin-sdk/src/admin-client.ts+++ b/packages/admin-sdk/src/admin-client.ts@@ -123,6 +123,13 @@ import type {PaymentMethodType,PaymentMethodUpdateParams,ProductUpdateParams,+ PromotionActionCreateParams,+ PromotionActionUpdateParams,+ PromotionCreateParams,+ PromotionRuleCreateParams,+ PromotionRuleUpdateParams,+ PromotionUpdateParams,+ ResourceTypeDefinition,StockItemUpdateParams,StockLocationCreateParams,StockLocationUpdateParams,@@ -140,6 +147,7 @@ import type {AdminUser,ApiKey,Category,+ CouponCode,Country,CreditCard,Customer,@@ -155,6 +163,9 @@ import type {Payment,PaymentMethod,Product,+ Promotion,+ PromotionAction,+ PromotionRule,Refund,Role,StockItem,@@ -913,6 +924,190 @@ export class AdminClient {this.request<{ data: PaymentMethodType[] }>('GET', '/payment_methods/types', options),}+ // ============================================+ // Promotions (with nested actions, rules, coupon codes)+ // ============================================++ readonly promotions = {+ list: (+ params?: ListParams & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<Promotion>> =>+ this.request<PaginatedResponse<Promotion>>('GET', '/promotions', {+ ...options,+ params: params ? transformListParams(params) : undefined,+ }),++ get: (+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions,+ ): Promise<Promotion> =>+ this.request<Promotion>('GET', `/promotions/${id}`, {+ ...options,+ params: getParams(params),+ }),++ create: (params: PromotionCreateParams, options?: RequestOptions): Promise<Promotion> =>+ this.request<Promotion>('POST', '/promotions', { ...options, body: params }),++ update: (+ id: string,+ params: PromotionUpdateParams,+ options?: RequestOptions,+ ): Promise<Promotion> =>+ this.request<Promotion>('PATCH', `/promotions/${id}`, { ...options, body: params }),++ delete: (id: string, options?: RequestOptions): Promise<void> =>+ this.request<void>('DELETE', `/promotions/${id}`, options),++ actions: {+ list: (+ promotionId: string,+ params?: ListParams & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<PromotionAction>> =>+ this.request<PaginatedResponse<PromotionAction>>(+ 'GET',+ `/promotions/${promotionId}/promotion_actions`,+ { ...options, params: params ? transformListParams(params) : undefined },+ ),++ get: (+ promotionId: string,+ id: string,+ options?: RequestOptions,+ ): Promise<PromotionAction> =>+ this.request<PromotionAction>(+ 'GET',+ `/promotions/${promotionId}/promotion_actions/${id}`,+ options,+ ),++ create: (+ promotionId: string,+ params: PromotionActionCreateParams,+ options?: RequestOptions,+ ): Promise<PromotionAction> =>+ this.request<PromotionAction>(+ 'POST',+ `/promotions/${promotionId}/promotion_actions`,+ { ...options, body: params },+ ),++ update: (+ promotionId: string,+ id: string,+ params: PromotionActionUpdateParams,+ options?: RequestOptions,+ ): Promise<PromotionAction> =>+ this.request<PromotionAction>(+ 'PATCH',+ `/promotions/${promotionId}/promotion_actions/${id}`,+ { ...options, body: params },+ ),++ delete: (promotionId: string, id: string, options?: RequestOptions): Promise<void> =>+ this.request<void>(+ 'DELETE',+ `/promotions/${promotionId}/promotion_actions/${id}`,+ options,+ ),+ },++ rules: {+ list: (+ promotionId: string,+ params?: ListParams & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<PromotionRule>> =>+ this.request<PaginatedResponse<PromotionRule>>(+ 'GET',+ `/promotions/${promotionId}/promotion_rules`,+ { ...options, params: params ? transformListParams(params) : undefined },+ ),++ get: (+ promotionId: string,+ id: string,+ options?: RequestOptions,+ ): Promise<PromotionRule> =>+ this.request<PromotionRule>(+ 'GET',+ `/promotions/${promotionId}/promotion_rules/${id}`,+ options,+ ),++ create: (+ promotionId: string,+ params: PromotionRuleCreateParams,+ options?: RequestOptions,+ ): Promise<PromotionRule> =>+ this.request<PromotionRule>(+ 'POST',+ `/promotions/${promotionId}/promotion_rules`,+ { ...options, body: params },+ ),++ update: (+ promotionId: string,+ id: string,+ params: PromotionRuleUpdateParams,+ options?: RequestOptions,+ ): Promise<PromotionRule> =>+ this.request<PromotionRule>(+ 'PATCH',+ `/promotions/${promotionId}/promotion_rules/${id}`,+ { ...options, body: params },+ ),++ delete: (promotionId: string, id: string, options?: RequestOptions): Promise<void> =>+ this.request<void>(+ 'DELETE',+ `/promotions/${promotionId}/promotion_rules/${id}`,+ options,+ ),+ },++ couponCodes: {+ list: (+ promotionId: string,+ params?: ListParams & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<CouponCode>> =>+ this.request<PaginatedResponse<CouponCode>>(+ 'GET',+ `/promotions/${promotionId}/coupon_codes`,+ { ...options, params: params ? transformListParams(params) : undefined },+ ),++ get: (promotionId: string, id: string, options?: RequestOptions): Promise<CouponCode> =>+ this.request<CouponCode>(+ 'GET',+ `/promotions/${promotionId}/coupon_codes/${id}`,+ options,+ ),+ },+ }++ readonly promotionActions = {+ types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>+ this.request<{ data: ResourceTypeDefinition[] }>(+ 'GET',+ '/promotion_actions/types',+ options,+ ),+ }++ readonly promotionRules = {+ types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>+ this.request<{ data: ResourceTypeDefinition[] }>(+ 'GET',+ '/promotion_rules/types',+ options,+ ),+ }+// ============================================// Tags// ============================================diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.tsindex ffbb57e9a3..1da97203c8 100644--- a/packages/admin-sdk/src/params.ts+++ b/packages/admin-sdk/src/params.ts@@ -463,6 +463,32 @@ export interface TaxCategoryUpdateParams {is_default?: boolean}+/**+ * One entry in `preference_schema`, describing a single tunable knob on+ * a STI subclass (payment provider, promotion action, promotion rule).+ *+ * The `type` mirrors Spree's preference type system — `string`, `text`,+ * `integer`, `decimal`, `boolean`, `array`, `password` — so admin UIs+ * can switch on it to render the right input widget.+ */+export interface PreferenceField {+ key: string+ type: string+ default: unknown+}++/**+ * The shape returned by `/<resource>/types` endpoints — one entry per+ * registered subclass with its preference schema. Used to build "Add+ * provider / action / rule" pickers and render generic preferences forms.+ */+export interface ResourceTypeDefinition {+ type: string+ label: string+ description: string | null+ preference_schema: PreferenceField[]+}+/*** Where the merchant exposes a payment method — `front_end` shows it on the* storefront, `back_end` only in the admin (e.g. manual check capture),@@ -480,6 +506,8 @@ export interface PaymentMethodCreateParams {auto_capture?: boolean | nullposition?: numbermetadata?: Record<string, unknown>+ /** Provider-specific configuration; values are coerced via the typed setters. */+ preferences?: Record<string, unknown>}export interface PaymentMethodUpdateParams {@@ -490,17 +518,18 @@ export interface PaymentMethodUpdateParams {auto_capture?: boolean | nullposition?: numbermetadata?: Record<string, unknown>+ preferences?: Record<string, unknown>}/*** One entry returned by `GET /payment_methods/types` — the registered list- * of available STI subclasses for the create form.+ * of available STI subclasses, with their per-provider preference schemas+ * for the universal configuration form.+ *+ * @deprecated Prefer `ResourceTypeDefinition`; this alias remains for+ * naming-symmetry with the controller. They are structurally identical.*/-export interface PaymentMethodType {- type: string- label: string- description: string | null-}+export type PaymentMethodType = ResourceTypeDefinition/*** Built-in `Spree::Export` subclasses. The server validates `type` against@@ -549,3 +578,66 @@ export type CustomFieldOwnerType =| 'Spree::Category'| 'Spree::OptionType'| (string & {})++export type PromotionKind = 'coupon_code' | 'automatic'++export interface PromotionCreateParams {+ name: string+ description?: string | null+ starts_at?: string | null+ expires_at?: string | null+ /** Required for single-code coupon promotions. Ignored when `multi_codes` is true. */+ code?: string | null+ usage_limit?: number | null+ match_policy?: 'all' | 'any'+ advertise?: boolean+ path?: string | null+ promotion_category_id?: string | null+ /** `coupon_code` requires a code (or multi_codes); `automatic` triggers without one. */+ kind?: PromotionKind+ /** When true, server auto-generates `number_of_codes` codes prefixed with `code_prefix`. */+ multi_codes?: boolean+ number_of_codes?: number | null+ code_prefix?: string | null+ store_ids?: string[]+ metadata?: Record<string, unknown>+}++export interface PromotionUpdateParams {+ name?: string+ description?: string | null+ starts_at?: string | null+ expires_at?: string | null+ code?: string | null+ usage_limit?: number | null+ match_policy?: 'all' | 'any'+ advertise?: boolean+ path?: string | null+ promotion_category_id?: string | null+ kind?: PromotionKind+ multi_codes?: boolean+ number_of_codes?: number | null+ code_prefix?: string | null+ store_ids?: string[]+ metadata?: Record<string, unknown>+}++export interface PromotionActionCreateParams {+ /** Fully-qualified STI subclass (`'Spree::Promotion::Actions::FreeShipping'`). */+ type: string+ preferences?: Record<string, unknown>+}++export interface PromotionActionUpdateParams {+ preferences?: Record<string, unknown>+}++export interface PromotionRuleCreateParams {+ /** Fully-qualified STI subclass (`'Spree::Promotion::Rules::Currency'`). */+ type: string+ preferences?: Record<string, unknown>+}++export interface PromotionRuleUpdateParams {+ preferences?: Record<string, unknown>+}diff --git a/packages/admin-sdk/src/types/generated/CouponCode.ts b/packages/admin-sdk/src/types/generated/CouponCode.tsnew file mode 100644index 0000000000..5a8d7ee648--- /dev/null+++ b/packages/admin-sdk/src/types/generated/CouponCode.ts@@ -0,0 +1,15 @@+// Typelizer digest b285f462f92bf9add46d0c2fe3da8079+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface CouponCode {+ id: string;+ code: string;+ state: string | null;+ created_at: string;+ updated_at: string;+ promotion_id: string;+ order_id: string | null;+}++export default CouponCode;diff --git a/packages/admin-sdk/src/types/generated/PaymentMethod.ts b/packages/admin-sdk/src/types/generated/PaymentMethod.tsindex 9025665278..351c79a238 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 b453b4488d0380fda2421df64d183a9e+// Typelizer digest cc3438e4b853754508739b48538ce6d9//// DO NOT MODIFY: This file was automatically generated by Typelizer.@@ -16,6 +16,8 @@ interface PaymentMethod {position: number;created_at: string;updated_at: string;+ preferences: Record<string, unknown>;+ preference_schema: Array<{ key: string; type: string; default: unknown }>;}export default PaymentMethod;diff --git a/packages/admin-sdk/src/types/generated/Promotion.ts b/packages/admin-sdk/src/types/generated/Promotion.tsnew file mode 100644index 0000000000..936fc4b133--- /dev/null+++ b/packages/admin-sdk/src/types/generated/Promotion.ts@@ -0,0 +1,29 @@+// Typelizer digest daaf48d7a11172b06ef73831eb336abd+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface Promotion {+ id: string;+ name: string;+ description: string | null;+ code: string | null;+ starts_at: string | null;+ expires_at: string | null;+ usage_limit: number | null;+ match_policy: string;+ advertise: boolean;+ path: string | null;+ kind: string;+ multi_codes: boolean;+ number_of_codes: number | null;+ code_prefix: string | null;+ promotion_category_id: string | null;+ metadata: Record<string, unknown>;+ created_at: string;+ updated_at: string;+ store_ids: Array<string>;+ action_ids: Array<string>;+ rule_ids: Array<string>;+}++export default Promotion;diff --git a/packages/admin-sdk/src/types/generated/PromotionAction.ts b/packages/admin-sdk/src/types/generated/PromotionAction.tsnew file mode 100644index 0000000000..ebcb7f20b7--- /dev/null+++ b/packages/admin-sdk/src/types/generated/PromotionAction.ts@@ -0,0 +1,16 @@+// Typelizer digest 69fdbc6c03b097d8aac101c19bc241f8+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface PromotionAction {+ id: string;+ type: string;+ created_at: string;+ updated_at: string;+ promotion_id: string;+ preferences: Record<string, unknown>;+ preference_schema: Array<{ key: string; type: string; default: unknown }>;+ label: string | null;+}++export default PromotionAction;diff --git a/packages/admin-sdk/src/types/generated/PromotionRule.ts b/packages/admin-sdk/src/types/generated/PromotionRule.tsnew file mode 100644index 0000000000..d1c00d3675--- /dev/null+++ b/packages/admin-sdk/src/types/generated/PromotionRule.ts@@ -0,0 +1,16 @@+// Typelizer digest 995c239ee5a3e49a2f61d25b068b5fee+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface PromotionRule {+ id: string;+ type: string;+ created_at: string;+ updated_at: string;+ promotion_id: string;+ preferences: Record<string, unknown>;+ preference_schema: Array<{ key: string; type: string; default: unknown }>;+ label: string | null;+}++export default PromotionRule;diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.tsindex 53c25a0beb..1dbde8d7da 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 fbfb43b4c1c1d460f556e07ba7ffc38e+// Typelizer digest 8b2fb3c06397f3f1bf93d3d55f32c826//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { default as Address } from './Address'@@ -8,6 +8,7 @@ export type { default as AllowedOrigin } from './AllowedOrigin'export type { default as ApiKey } from './ApiKey'export type { default as Category } from './Category'export type { default as Country } from './Country'+export type { default as CouponCode } from './CouponCode'export type { default as CreditCard } from './CreditCard'export type { default as CustomFieldDefinition } from './CustomFieldDefinition'export type { default as CustomField } from './CustomField'@@ -32,6 +33,9 @@ export type { default as PaymentSource } from './PaymentSource'export type { default as PriceHistory } from './PriceHistory'export type { default as Price } from './Price'export type { default as Product } from './Product'+export type { default as PromotionAction } from './PromotionAction'+export type { default as PromotionRule } from './PromotionRule'+export type { default as Promotion } from './Promotion'export type { default as Refund } from './Refund'export type { default as Reimbursement } from './Reimbursement'export type { default as ReturnAuthorization } from './ReturnAuthorization'diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.tsindex 2e8cbb843d..9b4a55570f 100644--- a/packages/admin-sdk/src/types/index.ts+++ b/packages/admin-sdk/src/types/index.ts@@ -15,6 +15,7 @@ export type { default as AdminUser } from './generated/AdminUser'export type { default as AllowedOrigin } from './generated/AllowedOrigin'export type { default as ApiKey } from './generated/ApiKey'export type { default as Category } from './generated/Category'+export type { default as CouponCode } from './generated/CouponCode'export type { default as Country } from './generated/Country'export type { default as CreditCard } from './generated/CreditCard'export type { default as Customer } from './generated/Customer'@@ -40,6 +41,9 @@ export type { default as PaymentSource } from './generated/PaymentSource'export type { default as Price } from './generated/Price'export type { default as PriceHistory } from './generated/PriceHistory'export type { default as Product } from './generated/Product'+export type { default as Promotion } from './generated/Promotion'+export type { default as PromotionAction } from './generated/PromotionAction'+export type { default as PromotionRule } from './generated/PromotionRule'export type { default as Refund } from './generated/Refund'export type { default as Reimbursement } from './generated/Reimbursement'export type { default as ReturnAuthorization } from './generated/ReturnAuthorization'