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
Add guide how to extend Admin SDK
Damian Legawieca2b5bada107b
diff --git a/docs/developer/sdk/admin/extending.mdx b/docs/developer/sdk/admin/extending.mdxnew file mode 100644index 0000000000..ace7f9d208--- /dev/null+++ b/docs/developer/sdk/admin/extending.mdx@@ -0,0 +1,70 @@+---+title: Custom Admin Endpoints+sidebarTitle: Custom Endpoints+description: Call custom Admin API endpoints using the SDK's built-in request method+---++The Admin SDK client exposes a `request` method — the same function that powers `client.products.list()`, `client.orders.get()`, and every other built-in resource. Use it to call any Admin API endpoint, including ones added by an extension gem that doesn't ship its own client.++```typescript+import { createAdminClient } from '@spree/admin-sdk'+import type { PaginatedResponse } from '@spree/admin-sdk'++const client = createAdminClient({+ baseUrl: 'https://api.mystore.com',+ token: 'sk_YOUR_SECRET_KEY', // or a JWT from /auth/login+})++interface Brand {+ id: string+ name: string+ slug: string | null+ description: string | null+ logo_url: string | null+}++// Paths are relative to /api/v3/admin+const brands = await client.request<PaginatedResponse<Brand>>('GET', '/brands')+const nike = await client.request<Brand>('GET', '/brands/nike')+```++`client.request` uses the same auth headers (secret API key *or* JWT, whichever was configured at client creation), retry logic, and base URL as every other resource on the client. The 401 → refresh → retry handshake that's wired up for the dashboard's user session applies to your custom endpoint too.++## Mutations++POST/PATCH/DELETE work the same way — pass `{ body }` for the request payload:++```typescript+const created = await client.request<Brand>('POST', '/brands', {+ body: { name: 'Acme', slug: 'acme', description: 'Quality goods since 1953' },+})++const updated = await client.request<Brand>('PATCH', `/brands/${created.id}`, {+ body: { description: 'New tagline' },+})++await client.request<void>('DELETE', `/brands/${created.id}`)+```++## Ransack filters and pagination++Standard list params work — pass them as the third argument's `params`:++```typescript+const result = await client.request<PaginatedResponse<Brand>>('GET', '/brands', {+ params: {+ page: 2,+ per_page: 25,+ filter: { name_cont: 'nike' },+ sort: '-created_at',+ },+})+```++The SDK transforms `filter`/`sort` into the Ransack-flavored query string the Admin API expects (`q[name_cont]=nike&q[s]=created_at%20desc`) automatically — same behavior as `client.products.list({ filter: ... })`.++## See also++- The [Store SDK extending guide](/developer/sdk/extending) covers the same pattern for storefront endpoints — the API is identical, only the base path (`/api/v3/store`) and auth header differ.+- The [Store API](/developer/tutorial/store-api) and [SDK](/developer/tutorial/sdk) tutorials walk through creating new Spree endpoints end-to-end (Rails controller, serializer, TypeScript types). Everything they show for the Store API applies equivalently for the Admin API.+- For building dashboard UI on top of your custom endpoint, see the [Dashboard Plugins](/developer/customization/dashboard-plugins) guide.diff --git a/docs/docs.json b/docs/docs.jsonindex 17a1222a78..838cadeb08 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -506,7 +506,8 @@"developer/sdk/admin/quickstart","developer/sdk/admin/authentication","developer/sdk/admin/resources",- "developer/sdk/admin/querying-and-errors"+ "developer/sdk/admin/querying-and-errors",+ "developer/sdk/admin/extending"]}]diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.tsindex e5895febb5..219cc758f5 100644--- a/packages/admin-sdk/src/admin-client.ts+++ b/packages/admin-sdk/src/admin-client.ts@@ -229,7 +229,28 @@ const CUSTOM_FIELD_OWNER_PATHS = {} as const satisfies Record<Exclude<CustomFieldOwnerType, string & {}>, string>export class AdminClient {- /** @internal */+ /**+ * Low-level request function for calling custom Admin API endpoints —+ * e.g. ones added by a Spree extension gem that doesn't ship its own+ * client.+ *+ * Uses the same auth headers (secret API key or JWT, whichever was+ * configured), retry logic, and base URL as the built-in resources.+ * Paths are relative to `/api/v3/admin`.+ *+ * @example+ * ```ts+ * import { createAdminClient } from '@spree/admin-sdk'+ * import type { PaginatedResponse } from '@spree/admin-sdk'+ *+ * interface Brand { id: string; name: string; slug: string }+ *+ * const client = createAdminClient({ baseUrl: 'https://api.shop.com', token: '...' })+ *+ * const brands = await client.request<PaginatedResponse<Brand>>('GET', '/brands')+ * const nike = await client.request<Brand>('GET', '/brands/nike')+ * ```+ */readonly request: RequestFnconstructor(request: RequestFn) {