@zippendo/sdk 1.0.2 → 1.1.0

package/README.md

@@ -42,6 +42,62 @@ Every call takes an `orgId` (your organization ID, found in the dashboard). It i
 call by design: one API token can be granted access to multiple organizations, and `orgId` selects
 which one the request acts on.
 
+## Brands
+
+A brand is a sub-account inside an organization: one company running several consumer-facing labels
+(say Acme and Globex) keeps each label's orders and shipments separate, with its own company name,
+address and logo on the documents its shipments produce. Scope a request to one brand with the
+`X-Zippendo-Brand` header, whose value is the brand's ID or slug.
+
+The header is not a method parameter — it applies uniformly to every operation, so set it once on the
+`Configuration` and every call made with it inherits it:
+
+```ts
+const acme = new Configuration({
+  accessToken: process.env.ZIPPENDO_API_TOKEN,
+  headers: { "X-Zippendo-Brand": "acme" }, // brand ID or slug
+})
+
+const shipments = new ShipmentsApi(acme)
+await shipments.listShipments({ orgId: "org_8f3kd92ld0", limit: 50 }) // Acme's shipments only
+```
+
+To address two brands from one process, build a `Configuration` per brand and pass each to its own
+resource clients. Omit the header and the request covers the whole organization — the behaviour of
+every existing token. A header naming a brand that does not exist in the organization is rejected
+with `404 BRAND_NOT_FOUND`.
+
+An API token created with a `brandId` is permanently confined to that brand and needs no header.
+Sending `X-Zippendo-Brand` naming a *different* brand on such a token is refused with
+`403 BRAND_ACCESS_DENIED` — the binding is never widened.
+
+### Managing brands
+
+Brands are managed with `BrandsApi`. Note this client is built from your organization-wide
+configuration, not a brand-scoped one — you are administering brands, not acting inside one:
+
+```ts
+const brands = new BrandsApi(config)
+
+const created = await brands.createOrgBrand({
+  orgId: "org_8f3kd92ld0",
+  createOrgBrandRequest: { name: "Acme", companyName: "Acme ApS" },
+})
+
+const page = await brands.listOrgBrands({ orgId: "org_8f3kd92ld0" })
+await brands.updateOrgBrand({
+  orgId: "org_8f3kd92ld0",
+  brandId: created.id,
+  updateOrgBrandRequest: { vatNumber: "DK12345678" },
+})
+await brands.archiveOrgBrand({ orgId: "org_8f3kd92ld0", brandId: created.id })
+```
+
+Retire a brand with `archiveOrgBrand` — archived brands keep their slug and can be restored with
+`unarchiveOrgBrand`. Permanent deletion is dashboard-only: it is refused while any order, shipment,
+member or token still references the brand. Brands require a plan that includes them; creating one
+past your plan's limit returns `403`.
+
 ## Listing & pagination
 
 List endpoints accept `page` (1-based) and `limit`, and return a page with `data` plus

package/dist/apis/AddressesApi.d.ts

@@ -1,6 +1,6 @@
 /**
  * Zippendo Public API
- * Public API documentation for Zippendo. Authenticate using your API token (Bearer token prefixed with zipp_).
+ * Public API documentation for Zippendo. Authenticate using your API token (Bearer token prefixed with zipp_).  **Brands (sub-accounts).** An organization can be split into brands, each keeping its own orders, shipments and configuration separate. There are two ways to scope requests to one brand, and NEITHER changes any request body:  1. **Bind the token.** Create an API token with a `brandId` and every request it makes is confined    to that brand — reads filtered, writes stamped. This is the recommended way to give a single    brand\'s team its own credential. 2. **Send the `X-Zippendo-Brand` header.** An organization-wide token can scope an individual    request by sending the brand\'s id or slug in this header. Most SDKs let you set it once on the    client so every call inherits it.  A brand-bound token that receives an `X-Zippendo-Brand` header naming a different brand is rejected with `403 BRAND_ACCESS_DENIED` — the binding is never widened. Omit both and requests cover the whole organization, which is the behaviour of every existing token.  Records that belong to no brand carry `brandId: null`. Configuration (carriers, shipping rules, addresses) with a null brand is organization-wide and remains visible inside every brand; orders and shipments with a null brand are only visible organization-wide.  Brands themselves are managed under the **Brands** tag. Retiring a brand is done with `POST /orgs/{orgId}/brands/{brandId}/archive` — permanent deletion is a dashboard-only action, since it is refused while any order, shipment, member or token still references the brand. Brands require a plan that includes them; creating one beyond your plan\'s limit returns `403`.
  *
  * The version of the OpenAPI document: 1.0.0
  * Contact: support@zippendo.com

package/dist/apis/AddressesApi.js

@@ -3,7 +3,7 @@
 /* eslint-disable */
 /**
  * Zippendo Public API
- * Public API documentation for Zippendo. Authenticate using your API token (Bearer token prefixed with zipp_).
+ * Public API documentation for Zippendo. Authenticate using your API token (Bearer token prefixed with zipp_).  **Brands (sub-accounts).** An organization can be split into brands, each keeping its own orders, shipments and configuration separate. There are two ways to scope requests to one brand, and NEITHER changes any request body:  1. **Bind the token.** Create an API token with a `brandId` and every request it makes is confined    to that brand — reads filtered, writes stamped. This is the recommended way to give a single    brand\'s team its own credential. 2. **Send the `X-Zippendo-Brand` header.** An organization-wide token can scope an individual    request by sending the brand\'s id or slug in this header. Most SDKs let you set it once on the    client so every call inherits it.  A brand-bound token that receives an `X-Zippendo-Brand` header naming a different brand is rejected with `403 BRAND_ACCESS_DENIED` — the binding is never widened. Omit both and requests cover the whole organization, which is the behaviour of every existing token.  Records that belong to no brand carry `brandId: null`. Configuration (carriers, shipping rules, addresses) with a null brand is organization-wide and remains visible inside every brand; orders and shipments with a null brand are only visible organization-wide.  Brands themselves are managed under the **Brands** tag. Retiring a brand is done with `POST /orgs/{orgId}/brands/{brandId}/archive` — permanent deletion is a dashboard-only action, since it is refused while any order, shipment, member or token still references the brand. Brands require a plan that includes them; creating one beyond your plan\'s limit returns `403`.
  *
  * The version of the OpenAPI document: 1.0.0
  * Contact: support@zippendo.com

package/dist/apis/BillingApi.d.ts

@@ -1,6 +1,6 @@
 /**
  * Zippendo Public API
- * Public API documentation for Zippendo. Authenticate using your API token (Bearer token prefixed with zipp_).
+ * Public API documentation for Zippendo. Authenticate using your API token (Bearer token prefixed with zipp_).  **Brands (sub-accounts).** An organization can be split into brands, each keeping its own orders, shipments and configuration separate. There are two ways to scope requests to one brand, and NEITHER changes any request body:  1. **Bind the token.** Create an API token with a `brandId` and every request it makes is confined    to that brand — reads filtered, writes stamped. This is the recommended way to give a single    brand\'s team its own credential. 2. **Send the `X-Zippendo-Brand` header.** An organization-wide token can scope an individual    request by sending the brand\'s id or slug in this header. Most SDKs let you set it once on the    client so every call inherits it.  A brand-bound token that receives an `X-Zippendo-Brand` header naming a different brand is rejected with `403 BRAND_ACCESS_DENIED` — the binding is never widened. Omit both and requests cover the whole organization, which is the behaviour of every existing token.  Records that belong to no brand carry `brandId: null`. Configuration (carriers, shipping rules, addresses) with a null brand is organization-wide and remains visible inside every brand; orders and shipments with a null brand are only visible organization-wide.  Brands themselves are managed under the **Brands** tag. Retiring a brand is done with `POST /orgs/{orgId}/brands/{brandId}/archive` — permanent deletion is a dashboard-only action, since it is refused while any order, shipment, member or token still references the brand. Brands require a plan that includes them; creating one beyond your plan\'s limit returns `403`.
  *
  * The version of the OpenAPI document: 1.0.0
  * Contact: support@zippendo.com

package/dist/apis/BillingApi.js

@@ -3,7 +3,7 @@
 /* eslint-disable */
 /**
  * Zippendo Public API
- * Public API documentation for Zippendo. Authenticate using your API token (Bearer token prefixed with zipp_).
+ * Public API documentation for Zippendo. Authenticate using your API token (Bearer token prefixed with zipp_).  **Brands (sub-accounts).** An organization can be split into brands, each keeping its own orders, shipments and configuration separate. There are two ways to scope requests to one brand, and NEITHER changes any request body:  1. **Bind the token.** Create an API token with a `brandId` and every request it makes is confined    to that brand — reads filtered, writes stamped. This is the recommended way to give a single    brand\'s team its own credential. 2. **Send the `X-Zippendo-Brand` header.** An organization-wide token can scope an individual    request by sending the brand\'s id or slug in this header. Most SDKs let you set it once on the    client so every call inherits it.  A brand-bound token that receives an `X-Zippendo-Brand` header naming a different brand is rejected with `403 BRAND_ACCESS_DENIED` — the binding is never widened. Omit both and requests cover the whole organization, which is the behaviour of every existing token.  Records that belong to no brand carry `brandId: null`. Configuration (carriers, shipping rules, addresses) with a null brand is organization-wide and remains visible inside every brand; orders and shipments with a null brand are only visible organization-wide.  Brands themselves are managed under the **Brands** tag. Retiring a brand is done with `POST /orgs/{orgId}/brands/{brandId}/archive` — permanent deletion is a dashboard-only action, since it is refused while any order, shipment, member or token still references the brand. Brands require a plan that includes them; creating one beyond your plan\'s limit returns `403`.
  *
  * The version of the OpenAPI document: 1.0.0
  * Contact: support@zippendo.com

package/dist/apis/BrandsApi.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Zippendo Public API
+ * Public API documentation for Zippendo. Authenticate using your API token (Bearer token prefixed with zipp_).  **Brands (sub-accounts).** An organization can be split into brands, each keeping its own orders, shipments and configuration separate. There are two ways to scope requests to one brand, and NEITHER changes any request body:  1. **Bind the token.** Create an API token with a `brandId` and every request it makes is confined    to that brand — reads filtered, writes stamped. This is the recommended way to give a single    brand\'s team its own credential. 2. **Send the `X-Zippendo-Brand` header.** An organization-wide token can scope an individual    request by sending the brand\'s id or slug in this header. Most SDKs let you set it once on the    client so every call inherits it.  A brand-bound token that receives an `X-Zippendo-Brand` header naming a different brand is rejected with `403 BRAND_ACCESS_DENIED` — the binding is never widened. Omit both and requests cover the whole organization, which is the behaviour of every existing token.  Records that belong to no brand carry `brandId: null`. Configuration (carriers, shipping rules, addresses) with a null brand is organization-wide and remains visible inside every brand; orders and shipments with a null brand are only visible organization-wide.  Brands themselves are managed under the **Brands** tag. Retiring a brand is done with `POST /orgs/{orgId}/brands/{brandId}/archive` — permanent deletion is a dashboard-only action, since it is refused while any order, shipment, member or token still references the brand. Brands require a plan that includes them; creating one beyond your plan\'s limit returns `403`.
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * Contact: support@zippendo.com
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+import * as runtime from '../runtime';
+import { type CheckBrandSlug200Response } from '../models/CheckBrandSlug200Response';
+import { type CreateOrgBrandRequest } from '../models/CreateOrgBrandRequest';
+import { type ListOrgBrands200Response } from '../models/ListOrgBrands200Response';
+import { type ListOrgBrands200ResponseDataInner } from '../models/ListOrgBrands200ResponseDataInner';
+import { type UpdateOrgBrandRequest } from '../models/UpdateOrgBrandRequest';
+export interface ArchiveOrgBrandRequest {
+    orgId: string;
+    brandId: string;
+}
+export interface CheckBrandSlugRequest {
+    orgId: string;
+    slug: string;
+}
+export interface CreateOrgBrandOperationRequest {
+    orgId: string;
+    createOrgBrandRequest: CreateOrgBrandRequest;
+}
+export interface DeleteBrandLogoRequest {
+    orgId: string;
+    brandId: string;
+}
+export interface GetBrandLogoRequest {
+    orgId: string;
+    brandId: string;
+}
+export interface GetOrgBrandRequest {
+    orgId: string;
+    brandId: string;
+}
+export interface ListOrgBrandsRequest {
+    orgId: string;
+    includeArchived?: string;
+}
+export interface UnarchiveOrgBrandRequest {
+    orgId: string;
+    brandId: string;
+}
+export interface UpdateOrgBrandOperationRequest {
+    orgId: string;
+    brandId: string;
+    updateOrgBrandRequest: UpdateOrgBrandRequest;
+}
+export interface UploadBrandLogoRequest {
+    orgId: string;
+    brandId: string;
+    file: Blob;
+}
+/**
+ *
+ */
+export declare class BrandsApi extends runtime.BaseAPI {
+    /**
+     * Creates request options for archiveOrgBrand without sending the request
+     */
+    archiveOrgBrandRequestOpts(requestParameters: ArchiveOrgBrandRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Archives a brand: it leaves the brand switcher and default listings, but its orders, shipments and settings are retained and remain visible in the organization-wide view.
+     * Archive brand
+     */
+    archiveOrgBrandRaw(requestParameters: ArchiveOrgBrandRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ListOrgBrands200ResponseDataInner>>;
+    /**
+     * Archives a brand: it leaves the brand switcher and default listings, but its orders, shipments and settings are retained and remain visible in the organization-wide view.
+     * Archive brand
+     */
+    archiveOrgBrand(requestParameters: ArchiveOrgBrandRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ListOrgBrands200ResponseDataInner>;
+    /**
+     * Creates request options for checkBrandSlug without sending the request
+     */
+    checkBrandSlugRequestOpts(requestParameters: CheckBrandSlugRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Reports whether a brand slug is free within this organization. Brand slugs are unique per organization, so the same slug may exist in another organization. Archived brands still hold their slug.
+     * Check brand slug availability
+     */
+    checkBrandSlugRaw(requestParameters: CheckBrandSlugRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<CheckBrandSlug200Response>>;
+    /**
+     * Reports whether a brand slug is free within this organization. Brand slugs are unique per organization, so the same slug may exist in another organization. Archived brands still hold their slug.
+     * Check brand slug availability
+     */
+    checkBrandSlug(requestParameters: CheckBrandSlugRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<CheckBrandSlug200Response>;
+    /**
+     * Creates request options for createOrgBrand without sending the request
+     */
+    createOrgBrandRequestOpts(requestParameters: CreateOrgBrandOperationRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Creates a brand (sub-account) in the organization. The slug is derived from the name when omitted. Requires a plan that includes brands.
+     * Create brand
+     */
+    createOrgBrandRaw(requestParameters: CreateOrgBrandOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ListOrgBrands200ResponseDataInner>>;
+    /**
+     * Creates a brand (sub-account) in the organization. The slug is derived from the name when omitted. Requires a plan that includes brands.
+     * Create brand
+     */
+    createOrgBrand(requestParameters: CreateOrgBrandOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ListOrgBrands200ResponseDataInner>;
+    /**
+     * Creates request options for deleteBrandLogo without sending the request
+     */
+    deleteBrandLogoRequestOpts(requestParameters: DeleteBrandLogoRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Removes a brand\'s logo. Its documents fall back to the organization\'s logo. Requires the brands and customBranding entitlements.
+     * Delete brand logo
+     */
+    deleteBrandLogoRaw(requestParameters: DeleteBrandLogoRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ListOrgBrands200ResponseDataInner>>;
+    /**
+     * Removes a brand\'s logo. Its documents fall back to the organization\'s logo. Requires the brands and customBranding entitlements.
+     * Delete brand logo
+     */
+    deleteBrandLogo(requestParameters: DeleteBrandLogoRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ListOrgBrands200ResponseDataInner>;
+    /**
+     * Creates request options for getBrandLogo without sending the request
+     */
+    getBrandLogoRequestOpts(requestParameters: GetBrandLogoRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Streams the brand\'s logo bytes. This is the URL returned as the brand\'s `logoUrl`.
+     * Get brand logo
+     */
+    getBrandLogoRaw(requestParameters: GetBrandLogoRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<Blob>>;
+    /**
+     * Streams the brand\'s logo bytes. This is the URL returned as the brand\'s `logoUrl`.
+     * Get brand logo
+     */
+    getBrandLogo(requestParameters: GetBrandLogoRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<Blob>;
+    /**
+     * Creates request options for getOrgBrand without sending the request
+     */
+    getOrgBrandRequestOpts(requestParameters: GetOrgBrandRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Returns a single brand (sub-account) by id.
+     * Get brand
+     */
+    getOrgBrandRaw(requestParameters: GetOrgBrandRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ListOrgBrands200ResponseDataInner>>;
+    /**
+     * Returns a single brand (sub-account) by id.
+     * Get brand
+     */
+    getOrgBrand(requestParameters: GetOrgBrandRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ListOrgBrands200ResponseDataInner>;
+    /**
+     * Creates request options for listOrgBrands without sending the request
+     */
+    listOrgBrandsRequestOpts(requestParameters: ListOrgBrandsRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Returns the organization\'s brands (sub-accounts). Archived brands are excluded unless `includeArchived` is set.
+     * List brands
+     */
+    listOrgBrandsRaw(requestParameters: ListOrgBrandsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ListOrgBrands200Response>>;
+    /**
+     * Returns the organization\'s brands (sub-accounts). Archived brands are excluded unless `includeArchived` is set.
+     * List brands
+     */
+    listOrgBrands(requestParameters: ListOrgBrandsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ListOrgBrands200Response>;
+    /**
+     * Creates request options for unarchiveOrgBrand without sending the request
+     */
+    unarchiveOrgBrandRequestOpts(requestParameters: UnarchiveOrgBrandRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Restores an archived brand so it appears in the brand switcher again.
+     * Unarchive brand
+     */
+    unarchiveOrgBrandRaw(requestParameters: UnarchiveOrgBrandRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ListOrgBrands200ResponseDataInner>>;
+    /**
+     * Restores an archived brand so it appears in the brand switcher again.
+     * Unarchive brand
+     */
+    unarchiveOrgBrand(requestParameters: UnarchiveOrgBrandRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ListOrgBrands200ResponseDataInner>;
+    /**
+     * Creates request options for updateOrgBrand without sending the request
+     */
+    updateOrgBrandRequestOpts(requestParameters: UpdateOrgBrandOperationRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Updates a brand\'s name, slug, identity overrides (company name, VAT, customs, address) and document colours. Null clears an override so the organization\'s value applies again.
+     * Update brand
+     */
+    updateOrgBrandRaw(requestParameters: UpdateOrgBrandOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ListOrgBrands200ResponseDataInner>>;
+    /**
+     * Updates a brand\'s name, slug, identity overrides (company name, VAT, customs, address) and document colours. Null clears an override so the organization\'s value applies again.
+     * Update brand
+     */
+    updateOrgBrand(requestParameters: UpdateOrgBrandOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ListOrgBrands200ResponseDataInner>;
+    /**
+     * Creates request options for uploadBrandLogo without sending the request
+     */
+    uploadBrandLogoRequestOpts(requestParameters: UploadBrandLogoRequest): Promise<runtime.RequestOpts>;
+    /**
+     * Uploads a brand\'s logo as multipart/form-data. Accepts PNG, JPG or WEBP up to 5MB and 4096×4096px; the image is re-encoded and stored. Documents for this brand\'s shipments use it instead of the organization\'s logo. Requires the brands and customBranding entitlements.
+     * Upload brand logo
+     */
+    uploadBrandLogoRaw(requestParameters: UploadBrandLogoRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<ListOrgBrands200ResponseDataInner>>;
+    /**
+     * Uploads a brand\'s logo as multipart/form-data. Accepts PNG, JPG or WEBP up to 5MB and 4096×4096px; the image is re-encoded and stored. Documents for this brand\'s shipments use it instead of the organization\'s logo. Requires the brands and customBranding entitlements.
+     * Upload brand logo
+     */
+    uploadBrandLogo(requestParameters: UploadBrandLogoRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ListOrgBrands200ResponseDataInner>;
+}