@timbrix/sdk 1.3.0 → 2.0.0

package/dist/index.d.mts

@@ -550,6 +550,33 @@ interface ListInvoicesResponse {
     limit: number;
     totalPages: number;
 }
+interface CfdiUsage {
+    plan: "starter" | "pro" | "business" | "enterprise";
+    /** null = unlimited (enterprise plan) */
+    cfdiIncluded: number | null;
+    cfdiUsedThisMonth: number;
+    /** null = unlimited (enterprise plan) */
+    cfdiRemaining: number | null;
+    periodResetsAt: string;
+}
+interface CancelInvoiceInput {
+    /** 01 = con relación (requiere folioSustitucion), 02 = sin relación, 03 = no se llevó a cabo la operación, 04 = operación nominativa relacionada en factura global */
+    motivo: "01" | "02" | "03" | "04";
+    folioSustitucion?: string;
+}
+interface InvoiceCancellation {
+    id: string;
+    invoiceId: string;
+    motivo: string;
+    folioSustitucion?: string | null;
+    requiresApproval: boolean;
+    respondBy?: string | null;
+    cancellationStatus: "pendiente" | "aceptada" | "rechazada";
+    requestedBy?: string | null;
+    resolvedBy?: string | null;
+    resolvedAt?: string | null;
+    createdAt: string;
+}
 interface TimbrixError {
     statusCode: number;
     message: string | string[];
@@ -606,25 +633,28 @@ declare class CustomersResource {
     private http;
     constructor(http: KyInstance);
     /**
-     * List all customers for an organization
+     * List all customers. Works with either an API key (organization
+     * resolved from the key — omit `organizationId`) or a Supabase bearer
+     * session (pass `organizationId` explicitly; sent as the
+     * `X-Organization-Id` header).
      */
-    list(organizationId: string): Promise<Customer[]>;
+    list(organizationId?: string): Promise<Customer[]>;
     /**
-     * Get a customer by ID
+     * Get a customer by ID. Same `organizationId` rules as `list`.
      */
-    get(organizationId: string, customerId: string): Promise<Customer>;
+    get(customerId: string, organizationId?: string): Promise<Customer>;
     /**
-     * Create a new customer
+     * Create a new customer. Same `organizationId` rules as `list`.
      */
-    create(organizationId: string, data: CreateCustomerInput): Promise<Customer>;
+    create(data: CreateCustomerInput, organizationId?: string): Promise<Customer>;
     /**
-     * Update a customer
+     * Update a customer. Same `organizationId` rules as `list`.
      */
-    update(organizationId: string, customerId: string, data: UpdateCustomerInput): Promise<Customer>;
+    update(customerId: string, data: UpdateCustomerInput, organizationId?: string): Promise<Customer>;
     /**
-     * Delete a customer
+     * Delete a customer. Same `organizationId` rules as `list`.
      */
-    delete(organizationId: string, customerId: string): Promise<void>;
+    delete(customerId: string, organizationId?: string): Promise<void>;
 }
 
 declare class InvoicesResource {
@@ -632,18 +662,28 @@ declare class InvoicesResource {
     constructor(http: KyInstance);
     /**
      * Create and stamp (timbrar) a CFDI 4.0 invoice via the configured PAC.
-     * Works with either a Supabase bearer session (internal dashboard, the
-     * user must be a member of `organizationId`) or an API key (external
-     * integrations, requires the `write:invoices` scope — the key must
-     * belong to `organizationId`).
+     * Works with either a Supabase bearer session (pass `organizationId`,
+     * the user must be a member of it) or an API key (external
+     * integrations, requires the `write:invoices` scope) — when the client
+     * is authenticated with an API key, `organizationId` can be omitted and
+     * is resolved from the key itself. When provided, sent as the
+     * `X-Organization-Id` header.
      */
-    create(organizationId: string, data: CreateInvoiceInput): Promise<Invoice>;
+    create(data: CreateInvoiceInput, organizationId?: string): Promise<Invoice>;
     /**
-     * List invoices for an organization, newest first. Works with either a
-     * Supabase bearer session or an API key (requires the `read:invoices`
-     * scope), same rules as `create`.
+     * Generate a PDF preview of a CFDI 4.0 invoice without stamping
+     * (timbrar) it via the PAC. Nothing is persisted and no stamping quota
+     * is consumed. Accepts the same body shape as `create`. Same auth rules
+     * as `create` — `organizationId` is optional when authenticated with an
+     * API key. When provided, sent as the `X-Organization-Id` header.
+     */
+    previewPdf(data: CreateInvoiceInput, organizationId?: string): Promise<Blob>;
+    /**
+     * List invoices for an organization, newest first. Same auth rules as
+     * `create` — `organizationId` is optional when authenticated with an
+     * API key. When provided, sent as the `X-Organization-Id` header.
      */
-    list(organizationId: string, params?: ListInvoicesParams): Promise<ListInvoicesResponse>;
+    list(params?: ListInvoicesParams, organizationId?: string): Promise<ListInvoicesResponse>;
     /**
      * Get a single CFDI 4.0 invoice by its folio fiscal (UUID). Works with
      * either a Supabase bearer session or an API key (requires the
@@ -662,6 +702,23 @@ declare class InvoicesResource {
      * scope).
      */
     getPdf(uuid: string): Promise<Blob>;
+    /**
+     * Cancel a stamped CFDI 4.0 invoice per SAT rules. Works with either a
+     * Supabase bearer session or an API key (requires the `write:invoices`
+     * scope). Returns immediately with `cancellationStatus: "pendiente"`
+     * when the SAT requires receptor approval — Timbrix cannot confirm that
+     * approval in real time.
+     */
+    cancel(uuid: string, data: CancelInvoiceInput): Promise<InvoiceCancellation>;
+    /**
+     * Get how many CFDI the organization has stamped this calendar month
+     * (Mexico City time) against its plan's included quota. `cfdiIncluded`
+     * and `cfdiRemaining` are `null` for the enterprise plan (unlimited).
+     * `organizationId` is optional when authenticated with an API key
+     * (resolved from the key). When provided, sent as the `X-Organization-Id`
+     * header.
+     */
+    usage(organizationId?: string): Promise<CfdiUsage>;
 }
 
 declare class OAuthResource {
@@ -762,25 +819,28 @@ declare class ProductsResource {
     private http;
     constructor(http: KyInstance);
     /**
-     * List products for an organization, with optional filters
+     * List products, with optional filters. Works with either an API key
+     * (organization resolved from the key — omit `organizationId`) or a
+     * Supabase bearer session (pass `organizationId` explicitly; sent as the
+     * `X-Organization-Id` header).
      */
-    list(organizationId: string, filters?: ListProductsFilters): Promise<Product[]>;
+    list(filters?: ListProductsFilters, organizationId?: string): Promise<Product[]>;
     /**
-     * Get a product by ID
+     * Get a product by ID. Same `organizationId` rules as `list`.
      */
-    get(organizationId: string, productId: string): Promise<Product>;
+    get(productId: string, organizationId?: string): Promise<Product>;
     /**
-     * Create a new product or service
+     * Create a new product or service. Same `organizationId` rules as `list`.
      */
-    create(organizationId: string, data: CreateProductInput): Promise<Product>;
+    create(data: CreateProductInput, organizationId?: string): Promise<Product>;
     /**
-     * Update a product
+     * Update a product. Same `organizationId` rules as `list`.
      */
-    update(organizationId: string, productId: string, data: UpdateProductInput): Promise<Product>;
+    update(productId: string, data: UpdateProductInput, organizationId?: string): Promise<Product>;
     /**
-     * Delete a product
+     * Delete a product. Same `organizationId` rules as `list`.
      */
-    delete(organizationId: string, productId: string): Promise<void>;
+    delete(productId: string, organizationId?: string): Promise<void>;
     /**
      * Bulk import products/services from a CSV file (multipart/form-data,
      * field name "file"). Works in both Node (18+) and browser environments,
@@ -792,9 +852,9 @@ declare class ProductsResource {
      * even if other rows fail, and every failure is reported with its row
      * number and reason.
      *
-     * Calls POST /organizations/:organizationId/products/import
+     * Calls POST /products/import. Same `organizationId` rules as `list`.
      */
-    importCsv(organizationId: string, file: Blob | File, filename?: string): Promise<ImportProductsCsvResult>;
+    importCsv(file: Blob | File, filename?: string, organizationId?: string): Promise<ImportProductsCsvResult>;
 }
 
 declare class SatResource {
@@ -919,4 +979,4 @@ declare class ApiKeyAuth implements AuthStrategy {
     applyAuth(options: Options): Options;
 }
 
-export { type ApiKey, ApiKeyAuth, type ApiKeyScope, type ApiKeyStats, type ApiKeyValidateResponse, ApiKeysResource, type AuthMode, AuthResource, type AuthStrategy, BearerAuth, type ClaveProdServ, type ClaveUnidad, type CreateApiKeyInput, type CreateApiKeyResponse, type CreateCustomerInput, type CreateInvoiceInput, type CreateOAuthAppInput, type CreateOrganizationInput, type CreateProductInput, type CreateWebhookInput, type Customer, type CustomerAddress, CustomersResource, type ExchangeCodeInput, type GenerateTokenInput, type ImportProductsCsvResult, type ImportProductsCsvRowError, type InviteMemberInput, type Invoice, type InvoiceCustomerInput, type InvoiceItemInput, type InvoiceListItem, type InvoiceTaxInput, InvoicesResource, type LegalAddress, type ListInvoicesParams, type ListInvoicesResponse, type ListProductsFilters, type ListRegimenesParams, type ListUsosCfdiParams, type LoginInput, type LoginResponse, type OAuthApp, type OAuthAppWithSecret, OAuthResource, type OAuthScope, type OAuthToken, type Organization, type OrganizationDetails, type OrganizationInvite, type OrganizationMember, type OrganizationRole, OrganizationsResource, type Product, type ProductTax, ProductsResource, type RefreshTokenInput, type RegimenFiscal, SatResource, type SearchClavesParams, type SearchClavesProdServResult, type SearchClavesUnidadResult, Timbrix, type TimbrixConfig, type TimbrixError, type TimbrixUser, type TipoPersona, type TokenResponse, type UpdateApiKeyInput, type UpdateCustomerInput, type UpdateLegalDataInput, type UpdateMemberRoleInput, type UpdateOAuthAppInput, type UpdateOrganizationInput, type UpdateProductInput, type UpdateWebhookInput, UsersResource, type UsoCfdi, type ValidateCertificateResponse, type Webhook, type WebhookDelivery, type WebhookEvent, WebhooksResource };
+export { type ApiKey, ApiKeyAuth, type ApiKeyScope, type ApiKeyStats, type ApiKeyValidateResponse, ApiKeysResource, type AuthMode, AuthResource, type AuthStrategy, BearerAuth, type CancelInvoiceInput, type CfdiUsage, type ClaveProdServ, type ClaveUnidad, type CreateApiKeyInput, type CreateApiKeyResponse, type CreateCustomerInput, type CreateInvoiceInput, type CreateOAuthAppInput, type CreateOrganizationInput, type CreateProductInput, type CreateWebhookInput, type Customer, type CustomerAddress, CustomersResource, type ExchangeCodeInput, type GenerateTokenInput, type ImportProductsCsvResult, type ImportProductsCsvRowError, type InviteMemberInput, type Invoice, type InvoiceCancellation, type InvoiceCustomerInput, type InvoiceItemInput, type InvoiceListItem, type InvoiceTaxInput, InvoicesResource, type LegalAddress, type ListInvoicesParams, type ListInvoicesResponse, type ListProductsFilters, type ListRegimenesParams, type ListUsosCfdiParams, type LoginInput, type LoginResponse, type OAuthApp, type OAuthAppWithSecret, OAuthResource, type OAuthScope, type OAuthToken, type Organization, type OrganizationDetails, type OrganizationInvite, type OrganizationMember, type OrganizationRole, OrganizationsResource, type Product, type ProductTax, ProductsResource, type RefreshTokenInput, type RegimenFiscal, SatResource, type SearchClavesParams, type SearchClavesProdServResult, type SearchClavesUnidadResult, Timbrix, type TimbrixConfig, type TimbrixError, type TimbrixUser, type TipoPersona, type TokenResponse, type UpdateApiKeyInput, type UpdateCustomerInput, type UpdateLegalDataInput, type UpdateMemberRoleInput, type UpdateOAuthAppInput, type UpdateOrganizationInput, type UpdateProductInput, type UpdateWebhookInput, UsersResource, type UsoCfdi, type ValidateCertificateResponse, type Webhook, type WebhookDelivery, type WebhookEvent, WebhooksResource };

package/dist/index.d.ts

@@ -550,6 +550,33 @@ interface ListInvoicesResponse {
     limit: number;
     totalPages: number;
 }
+interface CfdiUsage {
+    plan: "starter" | "pro" | "business" | "enterprise";
+    /** null = unlimited (enterprise plan) */
+    cfdiIncluded: number | null;
+    cfdiUsedThisMonth: number;
+    /** null = unlimited (enterprise plan) */
+    cfdiRemaining: number | null;
+    periodResetsAt: string;
+}
+interface CancelInvoiceInput {
+    /** 01 = con relación (requiere folioSustitucion), 02 = sin relación, 03 = no se llevó a cabo la operación, 04 = operación nominativa relacionada en factura global */
+    motivo: "01" | "02" | "03" | "04";
+    folioSustitucion?: string;
+}
+interface InvoiceCancellation {
+    id: string;
+    invoiceId: string;
+    motivo: string;
+    folioSustitucion?: string | null;
+    requiresApproval: boolean;
+    respondBy?: string | null;
+    cancellationStatus: "pendiente" | "aceptada" | "rechazada";
+    requestedBy?: string | null;
+    resolvedBy?: string | null;
+    resolvedAt?: string | null;
+    createdAt: string;
+}
 interface TimbrixError {
     statusCode: number;
     message: string | string[];
@@ -606,25 +633,28 @@ declare class CustomersResource {
     private http;
     constructor(http: KyInstance);
     /**
-     * List all customers for an organization
+     * List all customers. Works with either an API key (organization
+     * resolved from the key — omit `organizationId`) or a Supabase bearer
+     * session (pass `organizationId` explicitly; sent as the
+     * `X-Organization-Id` header).
      */
-    list(organizationId: string): Promise<Customer[]>;
+    list(organizationId?: string): Promise<Customer[]>;
     /**
-     * Get a customer by ID
+     * Get a customer by ID. Same `organizationId` rules as `list`.
      */
-    get(organizationId: string, customerId: string): Promise<Customer>;
+    get(customerId: string, organizationId?: string): Promise<Customer>;
     /**
-     * Create a new customer
+     * Create a new customer. Same `organizationId` rules as `list`.
      */
-    create(organizationId: string, data: CreateCustomerInput): Promise<Customer>;
+    create(data: CreateCustomerInput, organizationId?: string): Promise<Customer>;
     /**
-     * Update a customer
+     * Update a customer. Same `organizationId` rules as `list`.
      */
-    update(organizationId: string, customerId: string, data: UpdateCustomerInput): Promise<Customer>;
+    update(customerId: string, data: UpdateCustomerInput, organizationId?: string): Promise<Customer>;
     /**
-     * Delete a customer
+     * Delete a customer. Same `organizationId` rules as `list`.
      */
-    delete(organizationId: string, customerId: string): Promise<void>;
+    delete(customerId: string, organizationId?: string): Promise<void>;
 }
 
 declare class InvoicesResource {
@@ -632,18 +662,28 @@ declare class InvoicesResource {
     constructor(http: KyInstance);
     /**
      * Create and stamp (timbrar) a CFDI 4.0 invoice via the configured PAC.
-     * Works with either a Supabase bearer session (internal dashboard, the
-     * user must be a member of `organizationId`) or an API key (external
-     * integrations, requires the `write:invoices` scope — the key must
-     * belong to `organizationId`).
+     * Works with either a Supabase bearer session (pass `organizationId`,
+     * the user must be a member of it) or an API key (external
+     * integrations, requires the `write:invoices` scope) — when the client
+     * is authenticated with an API key, `organizationId` can be omitted and
+     * is resolved from the key itself. When provided, sent as the
+     * `X-Organization-Id` header.
      */
-    create(organizationId: string, data: CreateInvoiceInput): Promise<Invoice>;
+    create(data: CreateInvoiceInput, organizationId?: string): Promise<Invoice>;
     /**
-     * List invoices for an organization, newest first. Works with either a
-     * Supabase bearer session or an API key (requires the `read:invoices`
-     * scope), same rules as `create`.
+     * Generate a PDF preview of a CFDI 4.0 invoice without stamping
+     * (timbrar) it via the PAC. Nothing is persisted and no stamping quota
+     * is consumed. Accepts the same body shape as `create`. Same auth rules
+     * as `create` — `organizationId` is optional when authenticated with an
+     * API key. When provided, sent as the `X-Organization-Id` header.
+     */
+    previewPdf(data: CreateInvoiceInput, organizationId?: string): Promise<Blob>;
+    /**
+     * List invoices for an organization, newest first. Same auth rules as
+     * `create` — `organizationId` is optional when authenticated with an
+     * API key. When provided, sent as the `X-Organization-Id` header.
      */
-    list(organizationId: string, params?: ListInvoicesParams): Promise<ListInvoicesResponse>;
+    list(params?: ListInvoicesParams, organizationId?: string): Promise<ListInvoicesResponse>;
     /**
      * Get a single CFDI 4.0 invoice by its folio fiscal (UUID). Works with
      * either a Supabase bearer session or an API key (requires the
@@ -662,6 +702,23 @@ declare class InvoicesResource {
      * scope).
      */
     getPdf(uuid: string): Promise<Blob>;
+    /**
+     * Cancel a stamped CFDI 4.0 invoice per SAT rules. Works with either a
+     * Supabase bearer session or an API key (requires the `write:invoices`
+     * scope). Returns immediately with `cancellationStatus: "pendiente"`
+     * when the SAT requires receptor approval — Timbrix cannot confirm that
+     * approval in real time.
+     */
+    cancel(uuid: string, data: CancelInvoiceInput): Promise<InvoiceCancellation>;
+    /**
+     * Get how many CFDI the organization has stamped this calendar month
+     * (Mexico City time) against its plan's included quota. `cfdiIncluded`
+     * and `cfdiRemaining` are `null` for the enterprise plan (unlimited).
+     * `organizationId` is optional when authenticated with an API key
+     * (resolved from the key). When provided, sent as the `X-Organization-Id`
+     * header.
+     */
+    usage(organizationId?: string): Promise<CfdiUsage>;
 }
 
 declare class OAuthResource {
@@ -762,25 +819,28 @@ declare class ProductsResource {
     private http;
     constructor(http: KyInstance);
     /**
-     * List products for an organization, with optional filters
+     * List products, with optional filters. Works with either an API key
+     * (organization resolved from the key — omit `organizationId`) or a
+     * Supabase bearer session (pass `organizationId` explicitly; sent as the
+     * `X-Organization-Id` header).
      */
-    list(organizationId: string, filters?: ListProductsFilters): Promise<Product[]>;
+    list(filters?: ListProductsFilters, organizationId?: string): Promise<Product[]>;
     /**
-     * Get a product by ID
+     * Get a product by ID. Same `organizationId` rules as `list`.
      */
-    get(organizationId: string, productId: string): Promise<Product>;
+    get(productId: string, organizationId?: string): Promise<Product>;
     /**
-     * Create a new product or service
+     * Create a new product or service. Same `organizationId` rules as `list`.
      */
-    create(organizationId: string, data: CreateProductInput): Promise<Product>;
+    create(data: CreateProductInput, organizationId?: string): Promise<Product>;
     /**
-     * Update a product
+     * Update a product. Same `organizationId` rules as `list`.
      */
-    update(organizationId: string, productId: string, data: UpdateProductInput): Promise<Product>;
+    update(productId: string, data: UpdateProductInput, organizationId?: string): Promise<Product>;
     /**
-     * Delete a product
+     * Delete a product. Same `organizationId` rules as `list`.
      */
-    delete(organizationId: string, productId: string): Promise<void>;
+    delete(productId: string, organizationId?: string): Promise<void>;
     /**
      * Bulk import products/services from a CSV file (multipart/form-data,
      * field name "file"). Works in both Node (18+) and browser environments,
@@ -792,9 +852,9 @@ declare class ProductsResource {
      * even if other rows fail, and every failure is reported with its row
      * number and reason.
      *
-     * Calls POST /organizations/:organizationId/products/import
+     * Calls POST /products/import. Same `organizationId` rules as `list`.
      */
-    importCsv(organizationId: string, file: Blob | File, filename?: string): Promise<ImportProductsCsvResult>;
+    importCsv(file: Blob | File, filename?: string, organizationId?: string): Promise<ImportProductsCsvResult>;
 }
 
 declare class SatResource {
@@ -919,4 +979,4 @@ declare class ApiKeyAuth implements AuthStrategy {
     applyAuth(options: Options): Options;
 }
 
-export { type ApiKey, ApiKeyAuth, type ApiKeyScope, type ApiKeyStats, type ApiKeyValidateResponse, ApiKeysResource, type AuthMode, AuthResource, type AuthStrategy, BearerAuth, type ClaveProdServ, type ClaveUnidad, type CreateApiKeyInput, type CreateApiKeyResponse, type CreateCustomerInput, type CreateInvoiceInput, type CreateOAuthAppInput, type CreateOrganizationInput, type CreateProductInput, type CreateWebhookInput, type Customer, type CustomerAddress, CustomersResource, type ExchangeCodeInput, type GenerateTokenInput, type ImportProductsCsvResult, type ImportProductsCsvRowError, type InviteMemberInput, type Invoice, type InvoiceCustomerInput, type InvoiceItemInput, type InvoiceListItem, type InvoiceTaxInput, InvoicesResource, type LegalAddress, type ListInvoicesParams, type ListInvoicesResponse, type ListProductsFilters, type ListRegimenesParams, type ListUsosCfdiParams, type LoginInput, type LoginResponse, type OAuthApp, type OAuthAppWithSecret, OAuthResource, type OAuthScope, type OAuthToken, type Organization, type OrganizationDetails, type OrganizationInvite, type OrganizationMember, type OrganizationRole, OrganizationsResource, type Product, type ProductTax, ProductsResource, type RefreshTokenInput, type RegimenFiscal, SatResource, type SearchClavesParams, type SearchClavesProdServResult, type SearchClavesUnidadResult, Timbrix, type TimbrixConfig, type TimbrixError, type TimbrixUser, type TipoPersona, type TokenResponse, type UpdateApiKeyInput, type UpdateCustomerInput, type UpdateLegalDataInput, type UpdateMemberRoleInput, type UpdateOAuthAppInput, type UpdateOrganizationInput, type UpdateProductInput, type UpdateWebhookInput, UsersResource, type UsoCfdi, type ValidateCertificateResponse, type Webhook, type WebhookDelivery, type WebhookEvent, WebhooksResource };
+export { type ApiKey, ApiKeyAuth, type ApiKeyScope, type ApiKeyStats, type ApiKeyValidateResponse, ApiKeysResource, type AuthMode, AuthResource, type AuthStrategy, BearerAuth, type CancelInvoiceInput, type CfdiUsage, type ClaveProdServ, type ClaveUnidad, type CreateApiKeyInput, type CreateApiKeyResponse, type CreateCustomerInput, type CreateInvoiceInput, type CreateOAuthAppInput, type CreateOrganizationInput, type CreateProductInput, type CreateWebhookInput, type Customer, type CustomerAddress, CustomersResource, type ExchangeCodeInput, type GenerateTokenInput, type ImportProductsCsvResult, type ImportProductsCsvRowError, type InviteMemberInput, type Invoice, type InvoiceCancellation, type InvoiceCustomerInput, type InvoiceItemInput, type InvoiceListItem, type InvoiceTaxInput, InvoicesResource, type LegalAddress, type ListInvoicesParams, type ListInvoicesResponse, type ListProductsFilters, type ListRegimenesParams, type ListUsosCfdiParams, type LoginInput, type LoginResponse, type OAuthApp, type OAuthAppWithSecret, OAuthResource, type OAuthScope, type OAuthToken, type Organization, type OrganizationDetails, type OrganizationInvite, type OrganizationMember, type OrganizationRole, OrganizationsResource, type Product, type ProductTax, ProductsResource, type RefreshTokenInput, type RegimenFiscal, SatResource, type SearchClavesParams, type SearchClavesProdServResult, type SearchClavesUnidadResult, Timbrix, type TimbrixConfig, type TimbrixError, type TimbrixUser, type TipoPersona, type TokenResponse, type UpdateApiKeyInput, type UpdateCustomerInput, type UpdateLegalDataInput, type UpdateMemberRoleInput, type UpdateOAuthAppInput, type UpdateOrganizationInput, type UpdateProductInput, type UpdateWebhookInput, UsersResource, type UsoCfdi, type ValidateCertificateResponse, type Webhook, type WebhookDelivery, type WebhookEvent, WebhooksResource };

package/dist/index.js

@@ -172,38 +172,49 @@ var CustomersResource = class {
   }
   http;
   /**
-   * List all customers for an organization
+   * List all customers. Works with either an API key (organization
+   * resolved from the key — omit `organizationId`) or a Supabase bearer
+   * session (pass `organizationId` explicitly; sent as the
+   * `X-Organization-Id` header).
    */
   async list(organizationId) {
-    return this.http.get(`organizations/${organizationId}/customers`).json();
+    return this.http.get("customers", {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Get a customer by ID
+   * Get a customer by ID. Same `organizationId` rules as `list`.
    */
-  async get(organizationId, customerId) {
-    return this.http.get(`organizations/${organizationId}/customers/${customerId}`).json();
+  async get(customerId, organizationId) {
+    return this.http.get(`customers/${customerId}`, {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Create a new customer
+   * Create a new customer. Same `organizationId` rules as `list`.
    */
-  async create(organizationId, data) {
-    return this.http.post(`organizations/${organizationId}/customers`, { json: data }).json();
+  async create(data, organizationId) {
+    return this.http.post("customers", {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Update a customer
+   * Update a customer. Same `organizationId` rules as `list`.
    */
-  async update(organizationId, customerId, data) {
-    return this.http.put(`organizations/${organizationId}/customers/${customerId}`, {
-      json: data
+  async update(customerId, data, organizationId) {
+    return this.http.put(`customers/${customerId}`, {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
     }).json();
   }
   /**
-   * Delete a customer
+   * Delete a customer. Same `organizationId` rules as `list`.
    */
-  async delete(organizationId, customerId) {
-    await this.http.delete(
-      `organizations/${organizationId}/customers/${customerId}`
-    );
+  async delete(customerId, organizationId) {
+    await this.http.delete(`customers/${customerId}`, {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    });
   }
 };
 
@@ -215,27 +226,46 @@ var InvoicesResource = class {
   http;
   /**
    * Create and stamp (timbrar) a CFDI 4.0 invoice via the configured PAC.
-   * Works with either a Supabase bearer session (internal dashboard, the
-   * user must be a member of `organizationId`) or an API key (external
-   * integrations, requires the `write:invoices` scope — the key must
-   * belong to `organizationId`).
+   * Works with either a Supabase bearer session (pass `organizationId`,
+   * the user must be a member of it) or an API key (external
+   * integrations, requires the `write:invoices` scope) — when the client
+   * is authenticated with an API key, `organizationId` can be omitted and
+   * is resolved from the key itself. When provided, sent as the
+   * `X-Organization-Id` header.
+   */
+  async create(data, organizationId) {
+    return this.http.post("invoices", {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
+  }
+  /**
+   * Generate a PDF preview of a CFDI 4.0 invoice without stamping
+   * (timbrar) it via the PAC. Nothing is persisted and no stamping quota
+   * is consumed. Accepts the same body shape as `create`. Same auth rules
+   * as `create` — `organizationId` is optional when authenticated with an
+   * API key. When provided, sent as the `X-Organization-Id` header.
    */
-  async create(organizationId, data) {
-    return this.http.post(`organizations/${organizationId}/invoices`, { json: data }).json();
+  async previewPdf(data, organizationId) {
+    return this.http.post("invoices/preview/pdf", {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).blob();
   }
   /**
-   * List invoices for an organization, newest first. Works with either a
-   * Supabase bearer session or an API key (requires the `read:invoices`
-   * scope), same rules as `create`.
+   * List invoices for an organization, newest first. Same auth rules as
+   * `create` — `organizationId` is optional when authenticated with an
+   * API key. When provided, sent as the `X-Organization-Id` header.
    */
-  async list(organizationId, params) {
+  async list(params, organizationId) {
     const searchParams = {};
     if (params?.page !== void 0) searchParams.page = String(params.page);
     if (params?.limit !== void 0) searchParams.limit = String(params.limit);
     if (params?.type !== void 0) searchParams.type = params.type;
     if (params?.status !== void 0) searchParams.status = params.status;
-    return this.http.get(`organizations/${organizationId}/invoices`, {
-      searchParams: Object.keys(searchParams).length > 0 ? searchParams : void 0
+    return this.http.get("invoices", {
+      searchParams: Object.keys(searchParams).length > 0 ? searchParams : void 0,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
     }).json();
   }
   /**
@@ -262,6 +292,29 @@ var InvoicesResource = class {
   async getPdf(uuid) {
     return this.http.get(`invoices/${uuid}/pdf`).blob();
   }
+  /**
+   * Cancel a stamped CFDI 4.0 invoice per SAT rules. Works with either a
+   * Supabase bearer session or an API key (requires the `write:invoices`
+   * scope). Returns immediately with `cancellationStatus: "pendiente"`
+   * when the SAT requires receptor approval — Timbrix cannot confirm that
+   * approval in real time.
+   */
+  async cancel(uuid, data) {
+    return this.http.post(`invoices/${uuid}/cancel`, { json: data }).json();
+  }
+  /**
+   * Get how many CFDI the organization has stamped this calendar month
+   * (Mexico City time) against its plan's included quota. `cfdiIncluded`
+   * and `cfdiRemaining` are `null` for the enterprise plan (unlimited).
+   * `organizationId` is optional when authenticated with an API key
+   * (resolved from the key). When provided, sent as the `X-Organization-Id`
+   * header.
+   */
+  async usage(organizationId) {
+    return this.http.get("usage", {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
+  }
 };
 
 // src/resources/oauth.ts
@@ -434,45 +487,55 @@ var ProductsResource = class {
   }
   http;
   /**
-   * List products for an organization, with optional filters
+   * List products, with optional filters. Works with either an API key
+   * (organization resolved from the key — omit `organizationId`) or a
+   * Supabase bearer session (pass `organizationId` explicitly; sent as the
+   * `X-Organization-Id` header).
    */
-  async list(organizationId, filters) {
+  async list(filters, organizationId) {
     const searchParams = {};
     if (filters?.description) searchParams.description = filters.description;
     if (filters?.sku) searchParams.sku = filters.sku;
     if (filters?.productKey !== void 0)
       searchParams.productKey = String(filters.productKey);
-    return this.http.get(`organizations/${organizationId}/products`, {
-      searchParams: Object.keys(searchParams).length > 0 ? searchParams : void 0
+    return this.http.get("products", {
+      searchParams: Object.keys(searchParams).length > 0 ? searchParams : void 0,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
     }).json();
   }
   /**
-   * Get a product by ID
+   * Get a product by ID. Same `organizationId` rules as `list`.
    */
-  async get(organizationId, productId) {
-    return this.http.get(`organizations/${organizationId}/products/${productId}`).json();
+  async get(productId, organizationId) {
+    return this.http.get(`products/${productId}`, {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Create a new product or service
+   * Create a new product or service. Same `organizationId` rules as `list`.
    */
-  async create(organizationId, data) {
-    return this.http.post(`organizations/${organizationId}/products`, { json: data }).json();
+  async create(data, organizationId) {
+    return this.http.post("products", {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Update a product
+   * Update a product. Same `organizationId` rules as `list`.
    */
-  async update(organizationId, productId, data) {
-    return this.http.put(`organizations/${organizationId}/products/${productId}`, {
-      json: data
+  async update(productId, data, organizationId) {
+    return this.http.put(`products/${productId}`, {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
     }).json();
   }
   /**
-   * Delete a product
+   * Delete a product. Same `organizationId` rules as `list`.
    */
-  async delete(organizationId, productId) {
-    await this.http.delete(
-      `organizations/${organizationId}/products/${productId}`
-    );
+  async delete(productId, organizationId) {
+    await this.http.delete(`products/${productId}`, {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    });
   }
   /**
    * Bulk import products/services from a CSV file (multipart/form-data,
@@ -485,16 +548,19 @@ var ProductsResource = class {
    * even if other rows fail, and every failure is reported with its row
    * number and reason.
    *
-   * Calls POST /organizations/:organizationId/products/import
+   * Calls POST /products/import. Same `organizationId` rules as `list`.
    */
-  async importCsv(organizationId, file, filename = "products.csv") {
+  async importCsv(file, filename = "products.csv", organizationId) {
     const formData = new FormData();
     formData.append("file", file, filename);
-    return this.http.post(`organizations/${organizationId}/products/import`, {
+    return this.http.post("products/import", {
       body: formData,
       // Let fetch set the multipart Content-Type (with boundary) itself —
       // unset the JSON default header inherited from the client instance.
-      headers: { "Content-Type": void 0 }
+      headers: {
+        "Content-Type": void 0,
+        ...organizationId ? { "X-Organization-Id": organizationId } : void 0
+      }
     }).json();
   }
 };
@@ -655,14 +721,17 @@ var Timbrix = class {
   sat;
   invoices;
   constructor(config = {}) {
-    const baseUrl = config.baseUrl || "http://localhost:3001";
+    const baseUrl = (config.baseUrl || "http://localhost:3001").replace(
+      /\/?$/,
+      "/"
+    );
     if (config.bearerToken) {
       this.authStrategy = new BearerAuth(config.bearerToken);
     } else if (config.apiKey) {
       this.authStrategy = new ApiKeyAuth(config.apiKey);
     }
     this.http = import_ky.default.create({
-      prefixUrl: baseUrl,
+      baseUrl,
       headers: {
         "Content-Type": "application/json"
       },

package/dist/index.mjs

@@ -124,38 +124,49 @@ var CustomersResource = class {
   }
   http;
   /**
-   * List all customers for an organization
+   * List all customers. Works with either an API key (organization
+   * resolved from the key — omit `organizationId`) or a Supabase bearer
+   * session (pass `organizationId` explicitly; sent as the
+   * `X-Organization-Id` header).
    */
   async list(organizationId) {
-    return this.http.get(`organizations/${organizationId}/customers`).json();
+    return this.http.get("customers", {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Get a customer by ID
+   * Get a customer by ID. Same `organizationId` rules as `list`.
    */
-  async get(organizationId, customerId) {
-    return this.http.get(`organizations/${organizationId}/customers/${customerId}`).json();
+  async get(customerId, organizationId) {
+    return this.http.get(`customers/${customerId}`, {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Create a new customer
+   * Create a new customer. Same `organizationId` rules as `list`.
    */
-  async create(organizationId, data) {
-    return this.http.post(`organizations/${organizationId}/customers`, { json: data }).json();
+  async create(data, organizationId) {
+    return this.http.post("customers", {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Update a customer
+   * Update a customer. Same `organizationId` rules as `list`.
    */
-  async update(organizationId, customerId, data) {
-    return this.http.put(`organizations/${organizationId}/customers/${customerId}`, {
-      json: data
+  async update(customerId, data, organizationId) {
+    return this.http.put(`customers/${customerId}`, {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
     }).json();
   }
   /**
-   * Delete a customer
+   * Delete a customer. Same `organizationId` rules as `list`.
    */
-  async delete(organizationId, customerId) {
-    await this.http.delete(
-      `organizations/${organizationId}/customers/${customerId}`
-    );
+  async delete(customerId, organizationId) {
+    await this.http.delete(`customers/${customerId}`, {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    });
   }
 };
 
@@ -167,27 +178,46 @@ var InvoicesResource = class {
   http;
   /**
    * Create and stamp (timbrar) a CFDI 4.0 invoice via the configured PAC.
-   * Works with either a Supabase bearer session (internal dashboard, the
-   * user must be a member of `organizationId`) or an API key (external
-   * integrations, requires the `write:invoices` scope — the key must
-   * belong to `organizationId`).
+   * Works with either a Supabase bearer session (pass `organizationId`,
+   * the user must be a member of it) or an API key (external
+   * integrations, requires the `write:invoices` scope) — when the client
+   * is authenticated with an API key, `organizationId` can be omitted and
+   * is resolved from the key itself. When provided, sent as the
+   * `X-Organization-Id` header.
+   */
+  async create(data, organizationId) {
+    return this.http.post("invoices", {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
+  }
+  /**
+   * Generate a PDF preview of a CFDI 4.0 invoice without stamping
+   * (timbrar) it via the PAC. Nothing is persisted and no stamping quota
+   * is consumed. Accepts the same body shape as `create`. Same auth rules
+   * as `create` — `organizationId` is optional when authenticated with an
+   * API key. When provided, sent as the `X-Organization-Id` header.
    */
-  async create(organizationId, data) {
-    return this.http.post(`organizations/${organizationId}/invoices`, { json: data }).json();
+  async previewPdf(data, organizationId) {
+    return this.http.post("invoices/preview/pdf", {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).blob();
   }
   /**
-   * List invoices for an organization, newest first. Works with either a
-   * Supabase bearer session or an API key (requires the `read:invoices`
-   * scope), same rules as `create`.
+   * List invoices for an organization, newest first. Same auth rules as
+   * `create` — `organizationId` is optional when authenticated with an
+   * API key. When provided, sent as the `X-Organization-Id` header.
    */
-  async list(organizationId, params) {
+  async list(params, organizationId) {
     const searchParams = {};
     if (params?.page !== void 0) searchParams.page = String(params.page);
     if (params?.limit !== void 0) searchParams.limit = String(params.limit);
     if (params?.type !== void 0) searchParams.type = params.type;
     if (params?.status !== void 0) searchParams.status = params.status;
-    return this.http.get(`organizations/${organizationId}/invoices`, {
-      searchParams: Object.keys(searchParams).length > 0 ? searchParams : void 0
+    return this.http.get("invoices", {
+      searchParams: Object.keys(searchParams).length > 0 ? searchParams : void 0,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
     }).json();
   }
   /**
@@ -214,6 +244,29 @@ var InvoicesResource = class {
   async getPdf(uuid) {
     return this.http.get(`invoices/${uuid}/pdf`).blob();
   }
+  /**
+   * Cancel a stamped CFDI 4.0 invoice per SAT rules. Works with either a
+   * Supabase bearer session or an API key (requires the `write:invoices`
+   * scope). Returns immediately with `cancellationStatus: "pendiente"`
+   * when the SAT requires receptor approval — Timbrix cannot confirm that
+   * approval in real time.
+   */
+  async cancel(uuid, data) {
+    return this.http.post(`invoices/${uuid}/cancel`, { json: data }).json();
+  }
+  /**
+   * Get how many CFDI the organization has stamped this calendar month
+   * (Mexico City time) against its plan's included quota. `cfdiIncluded`
+   * and `cfdiRemaining` are `null` for the enterprise plan (unlimited).
+   * `organizationId` is optional when authenticated with an API key
+   * (resolved from the key). When provided, sent as the `X-Organization-Id`
+   * header.
+   */
+  async usage(organizationId) {
+    return this.http.get("usage", {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
+  }
 };
 
 // src/resources/oauth.ts
@@ -386,45 +439,55 @@ var ProductsResource = class {
   }
   http;
   /**
-   * List products for an organization, with optional filters
+   * List products, with optional filters. Works with either an API key
+   * (organization resolved from the key — omit `organizationId`) or a
+   * Supabase bearer session (pass `organizationId` explicitly; sent as the
+   * `X-Organization-Id` header).
    */
-  async list(organizationId, filters) {
+  async list(filters, organizationId) {
     const searchParams = {};
     if (filters?.description) searchParams.description = filters.description;
     if (filters?.sku) searchParams.sku = filters.sku;
     if (filters?.productKey !== void 0)
       searchParams.productKey = String(filters.productKey);
-    return this.http.get(`organizations/${organizationId}/products`, {
-      searchParams: Object.keys(searchParams).length > 0 ? searchParams : void 0
+    return this.http.get("products", {
+      searchParams: Object.keys(searchParams).length > 0 ? searchParams : void 0,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
     }).json();
   }
   /**
-   * Get a product by ID
+   * Get a product by ID. Same `organizationId` rules as `list`.
    */
-  async get(organizationId, productId) {
-    return this.http.get(`organizations/${organizationId}/products/${productId}`).json();
+  async get(productId, organizationId) {
+    return this.http.get(`products/${productId}`, {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Create a new product or service
+   * Create a new product or service. Same `organizationId` rules as `list`.
    */
-  async create(organizationId, data) {
-    return this.http.post(`organizations/${organizationId}/products`, { json: data }).json();
+  async create(data, organizationId) {
+    return this.http.post("products", {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    }).json();
   }
   /**
-   * Update a product
+   * Update a product. Same `organizationId` rules as `list`.
    */
-  async update(organizationId, productId, data) {
-    return this.http.put(`organizations/${organizationId}/products/${productId}`, {
-      json: data
+  async update(productId, data, organizationId) {
+    return this.http.put(`products/${productId}`, {
+      json: data,
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
     }).json();
   }
   /**
-   * Delete a product
+   * Delete a product. Same `organizationId` rules as `list`.
    */
-  async delete(organizationId, productId) {
-    await this.http.delete(
-      `organizations/${organizationId}/products/${productId}`
-    );
+  async delete(productId, organizationId) {
+    await this.http.delete(`products/${productId}`, {
+      headers: organizationId ? { "X-Organization-Id": organizationId } : void 0
+    });
   }
   /**
    * Bulk import products/services from a CSV file (multipart/form-data,
@@ -437,16 +500,19 @@ var ProductsResource = class {
    * even if other rows fail, and every failure is reported with its row
    * number and reason.
    *
-   * Calls POST /organizations/:organizationId/products/import
+   * Calls POST /products/import. Same `organizationId` rules as `list`.
    */
-  async importCsv(organizationId, file, filename = "products.csv") {
+  async importCsv(file, filename = "products.csv", organizationId) {
     const formData = new FormData();
     formData.append("file", file, filename);
-    return this.http.post(`organizations/${organizationId}/products/import`, {
+    return this.http.post("products/import", {
       body: formData,
       // Let fetch set the multipart Content-Type (with boundary) itself —
       // unset the JSON default header inherited from the client instance.
-      headers: { "Content-Type": void 0 }
+      headers: {
+        "Content-Type": void 0,
+        ...organizationId ? { "X-Organization-Id": organizationId } : void 0
+      }
     }).json();
   }
 };
@@ -607,14 +673,17 @@ var Timbrix = class {
   sat;
   invoices;
   constructor(config = {}) {
-    const baseUrl = config.baseUrl || "http://localhost:3001";
+    const baseUrl = (config.baseUrl || "http://localhost:3001").replace(
+      /\/?$/,
+      "/"
+    );
     if (config.bearerToken) {
       this.authStrategy = new BearerAuth(config.bearerToken);
     } else if (config.apiKey) {
       this.authStrategy = new ApiKeyAuth(config.apiKey);
     }
     this.http = ky.create({
-      prefixUrl: baseUrl,
+      baseUrl,
       headers: {
         "Content-Type": "application/json"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timbrix/sdk",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "TypeScript SDK for Timbrix API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",