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 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.md
new file mode 100644
index 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.ts
index 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.ts
index 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 | null
position?: number
metadata?: 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 | null
position?: number
metadata?: 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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'