@timbrix/sdk 0.3.0 → 1.0.0

package/dist/index.d.mts

@@ -201,7 +201,7 @@ interface WebhookDelivery {
     success: boolean;
     createdAt: string;
 }
-type ApiKeyScope = "read:user" | "write:user" | "read:organization" | "write:organization" | "read:members" | "write:members" | "read:webhooks" | "write:webhooks" | "read:api-keys" | "write:api-keys";
+type ApiKeyScope = "read:user" | "write:user" | "read:organization" | "write:organization" | "read:members" | "write:members" | "read:webhooks" | "write:webhooks" | "read:api-keys" | "write:api-keys" | "read:invoices" | "write:invoices";
 interface ApiKey {
     id: string;
     organizationId: string;
@@ -408,6 +408,72 @@ interface ListUsosCfdiParams {
     tipoPersona?: TipoPersona;
     regimen?: string;
 }
+interface InvoiceCustomerInput {
+    legalName: string;
+    taxId: string;
+    /** SAT régimen fiscal code — required unless the customer is público en general */
+    taxSystem?: string;
+    zip?: string;
+}
+interface InvoiceTaxInput {
+    type: string;
+    factorType: string;
+    rate?: string;
+    base?: number;
+    amount?: number;
+}
+interface InvoiceItemInput {
+    quantity: number;
+    description: string;
+    unitPrice: number;
+    amount: number;
+    productKey: string;
+    unitKey: string;
+    unit?: string;
+    taxObject?: string;
+    taxes?: InvoiceTaxInput[];
+}
+interface CreateInvoiceInput {
+    /** Ingreso, Egreso, or Traslado — default: I */
+    type?: "I" | "E" | "T";
+    series: string;
+    folioNumber: string;
+    date: string;
+    paymentForm: string;
+    /** Default: PUE */
+    paymentMethod?: "PUE" | "PPD";
+    /** Default: MXN */
+    currency?: string;
+    /** Default: 1 */
+    exchange?: number;
+    /** SAT clave de exportación — default: 01 */
+    export?: string;
+    /** SAT uso CFDI catalog code */
+    use: string;
+    /** Inline customer — mutually exclusive with customerId */
+    customer?: InvoiceCustomerInput;
+    /** Existing customer ID — mutually exclusive with customer */
+    customerId?: string;
+    items: InvoiceItemInput[];
+    /**
+     * Client-supplied key to safely retry this request without
+     * double-stamping. If an invoice was already created for this
+     * organization with the same key, that invoice is returned instead of
+     * stamping again.
+     */
+    idempotencyKey?: string;
+}
+interface Invoice {
+    id: string;
+    uuid: string;
+    status: "valid";
+    series: string;
+    folioNumber: string;
+    total: number;
+    date: string;
+    xml: string;
+    createdAt: string;
+}
 interface TimbrixError {
     statusCode: number;
     message: string | string[];
@@ -485,6 +551,17 @@ declare class CustomersResource {
     delete(organizationId: string, customerId: string): Promise<void>;
 }
 
+declare class InvoicesResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * Create and stamp (timbrar) a CFDI 4.0 invoice via the configured PAC.
+     * Requires an API-key-authenticated client — the issuing organization is
+     * resolved from the key, there is no organizationId parameter.
+     */
+    create(data: CreateInvoiceInput): Promise<Invoice>;
+}
+
 declare class OAuthResource {
     private http;
     constructor(http: KyInstance);
@@ -687,6 +764,7 @@ declare class Timbrix {
     readonly oauth: OAuthResource;
     readonly products: ProductsResource;
     readonly sat: SatResource;
+    readonly invoices: InvoicesResource;
     constructor(config?: TimbrixConfig);
     /**
      * Update authentication strategy (useful for CLI when token changes)
@@ -715,4 +793,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 CreateApiKeyInput, type CreateApiKeyResponse, type CreateCustomerInput, type CreateOAuthAppInput, type CreateOrganizationInput, type CreateProductInput, type CreateWebhookInput, type Customer, type CustomerAddress, CustomersResource, type ExchangeCodeInput, type GenerateTokenInput, type InviteMemberInput, type LegalAddress, 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, 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 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 InviteMemberInput, type Invoice, type InvoiceCustomerInput, type InvoiceItemInput, type InvoiceTaxInput, InvoicesResource, type LegalAddress, 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, 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

@@ -201,7 +201,7 @@ interface WebhookDelivery {
     success: boolean;
     createdAt: string;
 }
-type ApiKeyScope = "read:user" | "write:user" | "read:organization" | "write:organization" | "read:members" | "write:members" | "read:webhooks" | "write:webhooks" | "read:api-keys" | "write:api-keys";
+type ApiKeyScope = "read:user" | "write:user" | "read:organization" | "write:organization" | "read:members" | "write:members" | "read:webhooks" | "write:webhooks" | "read:api-keys" | "write:api-keys" | "read:invoices" | "write:invoices";
 interface ApiKey {
     id: string;
     organizationId: string;
@@ -408,6 +408,72 @@ interface ListUsosCfdiParams {
     tipoPersona?: TipoPersona;
     regimen?: string;
 }
+interface InvoiceCustomerInput {
+    legalName: string;
+    taxId: string;
+    /** SAT régimen fiscal code — required unless the customer is público en general */
+    taxSystem?: string;
+    zip?: string;
+}
+interface InvoiceTaxInput {
+    type: string;
+    factorType: string;
+    rate?: string;
+    base?: number;
+    amount?: number;
+}
+interface InvoiceItemInput {
+    quantity: number;
+    description: string;
+    unitPrice: number;
+    amount: number;
+    productKey: string;
+    unitKey: string;
+    unit?: string;
+    taxObject?: string;
+    taxes?: InvoiceTaxInput[];
+}
+interface CreateInvoiceInput {
+    /** Ingreso, Egreso, or Traslado — default: I */
+    type?: "I" | "E" | "T";
+    series: string;
+    folioNumber: string;
+    date: string;
+    paymentForm: string;
+    /** Default: PUE */
+    paymentMethod?: "PUE" | "PPD";
+    /** Default: MXN */
+    currency?: string;
+    /** Default: 1 */
+    exchange?: number;
+    /** SAT clave de exportación — default: 01 */
+    export?: string;
+    /** SAT uso CFDI catalog code */
+    use: string;
+    /** Inline customer — mutually exclusive with customerId */
+    customer?: InvoiceCustomerInput;
+    /** Existing customer ID — mutually exclusive with customer */
+    customerId?: string;
+    items: InvoiceItemInput[];
+    /**
+     * Client-supplied key to safely retry this request without
+     * double-stamping. If an invoice was already created for this
+     * organization with the same key, that invoice is returned instead of
+     * stamping again.
+     */
+    idempotencyKey?: string;
+}
+interface Invoice {
+    id: string;
+    uuid: string;
+    status: "valid";
+    series: string;
+    folioNumber: string;
+    total: number;
+    date: string;
+    xml: string;
+    createdAt: string;
+}
 interface TimbrixError {
     statusCode: number;
     message: string | string[];
@@ -485,6 +551,17 @@ declare class CustomersResource {
     delete(organizationId: string, customerId: string): Promise<void>;
 }
 
+declare class InvoicesResource {
+    private http;
+    constructor(http: KyInstance);
+    /**
+     * Create and stamp (timbrar) a CFDI 4.0 invoice via the configured PAC.
+     * Requires an API-key-authenticated client — the issuing organization is
+     * resolved from the key, there is no organizationId parameter.
+     */
+    create(data: CreateInvoiceInput): Promise<Invoice>;
+}
+
 declare class OAuthResource {
     private http;
     constructor(http: KyInstance);
@@ -687,6 +764,7 @@ declare class Timbrix {
     readonly oauth: OAuthResource;
     readonly products: ProductsResource;
     readonly sat: SatResource;
+    readonly invoices: InvoicesResource;
     constructor(config?: TimbrixConfig);
     /**
      * Update authentication strategy (useful for CLI when token changes)
@@ -715,4 +793,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 CreateApiKeyInput, type CreateApiKeyResponse, type CreateCustomerInput, type CreateOAuthAppInput, type CreateOrganizationInput, type CreateProductInput, type CreateWebhookInput, type Customer, type CustomerAddress, CustomersResource, type ExchangeCodeInput, type GenerateTokenInput, type InviteMemberInput, type LegalAddress, 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, 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 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 InviteMemberInput, type Invoice, type InvoiceCustomerInput, type InvoiceItemInput, type InvoiceTaxInput, InvoicesResource, type LegalAddress, 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, 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

@@ -35,6 +35,7 @@ __export(index_exports, {
   AuthResource: () => AuthResource,
   BearerAuth: () => BearerAuth,
   CustomersResource: () => CustomersResource,
+  InvoicesResource: () => InvoicesResource,
   OAuthResource: () => OAuthResource,
   OrganizationsResource: () => OrganizationsResource,
   ProductsResource: () => ProductsResource,
@@ -53,6 +54,7 @@ var BearerAuth = class {
   constructor(token) {
     this.token = token;
   }
+  token;
   getHeaders() {
     return {
       Authorization: `Bearer ${this.token}`
@@ -72,6 +74,7 @@ var ApiKeyAuth = class {
   constructor(apiKey) {
     this.apiKey = apiKey;
   }
+  apiKey;
   getHeaders() {
     return {
       "X-API-Key": this.apiKey
@@ -93,6 +96,7 @@ var ApiKeysResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List all API keys for an organization
    */
@@ -146,6 +150,7 @@ var AuthResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * Login with email and password. Returns an access token.
    */
@@ -165,6 +170,7 @@ var CustomersResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List all customers for an organization
    */
@@ -201,11 +207,28 @@ var CustomersResource = class {
   }
 };
 
+// src/resources/invoices.ts
+var InvoicesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Create and stamp (timbrar) a CFDI 4.0 invoice via the configured PAC.
+   * Requires an API-key-authenticated client — the issuing organization is
+   * resolved from the key, there is no organizationId parameter.
+   */
+  async create(data) {
+    return this.http.post("invoices", { json: data }).json();
+  }
+};
+
 // src/resources/oauth.ts
 var OAuthResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   // ─── App Management ─────────────────────────────────────────────────────────
   /**
    * Create a new OAuth application. Client secret is returned only once.
@@ -294,6 +317,7 @@ var OrganizationsResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * Create a new organization
    */
@@ -367,6 +391,7 @@ var ProductsResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List products for an organization, with optional filters
    */
@@ -415,6 +440,7 @@ var SatResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List régimenes fiscales from the SAT catalog
    * Calls GET /sat/regimenes-fiscales
@@ -445,6 +471,7 @@ var UsersResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * Get the currently authenticated user
    */
@@ -476,6 +503,7 @@ var WebhooksResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List all webhooks for an organization
    */
@@ -537,8 +565,9 @@ var Timbrix = class {
   oauth;
   products;
   sat;
+  invoices;
   constructor(config = {}) {
-    const baseUrl = config.baseUrl || "http://localhost:3001/api";
+    const baseUrl = config.baseUrl || "http://localhost:3001";
     if (config.bearerToken) {
       this.authStrategy = new BearerAuth(config.bearerToken);
     } else if (config.apiKey) {
@@ -551,7 +580,7 @@ var Timbrix = class {
       },
       hooks: {
         beforeRequest: [
-          (request) => {
+          ({ request }) => {
             if (this.authStrategy) {
               const authHeaders = this.authStrategy.getHeaders();
               Object.entries(authHeaders).forEach(([key, value]) => {
@@ -571,6 +600,7 @@ var Timbrix = class {
     this.oauth = new OAuthResource(this.http);
     this.products = new ProductsResource(this.http);
     this.sat = new SatResource(this.http);
+    this.invoices = new InvoicesResource(this.http);
   }
   /**
    * Update authentication strategy (useful for CLI when token changes)
@@ -598,6 +628,7 @@ var Timbrix = class {
   AuthResource,
   BearerAuth,
   CustomersResource,
+  InvoicesResource,
   OAuthResource,
   OrganizationsResource,
   ProductsResource,

package/dist/index.mjs

@@ -6,6 +6,7 @@ var BearerAuth = class {
   constructor(token) {
     this.token = token;
   }
+  token;
   getHeaders() {
     return {
       Authorization: `Bearer ${this.token}`
@@ -25,6 +26,7 @@ var ApiKeyAuth = class {
   constructor(apiKey) {
     this.apiKey = apiKey;
   }
+  apiKey;
   getHeaders() {
     return {
       "X-API-Key": this.apiKey
@@ -46,6 +48,7 @@ var ApiKeysResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List all API keys for an organization
    */
@@ -99,6 +102,7 @@ var AuthResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * Login with email and password. Returns an access token.
    */
@@ -118,6 +122,7 @@ var CustomersResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List all customers for an organization
    */
@@ -154,11 +159,28 @@ var CustomersResource = class {
   }
 };
 
+// src/resources/invoices.ts
+var InvoicesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Create and stamp (timbrar) a CFDI 4.0 invoice via the configured PAC.
+   * Requires an API-key-authenticated client — the issuing organization is
+   * resolved from the key, there is no organizationId parameter.
+   */
+  async create(data) {
+    return this.http.post("invoices", { json: data }).json();
+  }
+};
+
 // src/resources/oauth.ts
 var OAuthResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   // ─── App Management ─────────────────────────────────────────────────────────
   /**
    * Create a new OAuth application. Client secret is returned only once.
@@ -247,6 +269,7 @@ var OrganizationsResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * Create a new organization
    */
@@ -320,6 +343,7 @@ var ProductsResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List products for an organization, with optional filters
    */
@@ -368,6 +392,7 @@ var SatResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List régimenes fiscales from the SAT catalog
    * Calls GET /sat/regimenes-fiscales
@@ -398,6 +423,7 @@ var UsersResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * Get the currently authenticated user
    */
@@ -429,6 +455,7 @@ var WebhooksResource = class {
   constructor(http) {
     this.http = http;
   }
+  http;
   /**
    * List all webhooks for an organization
    */
@@ -490,8 +517,9 @@ var Timbrix = class {
   oauth;
   products;
   sat;
+  invoices;
   constructor(config = {}) {
-    const baseUrl = config.baseUrl || "http://localhost:3001/api";
+    const baseUrl = config.baseUrl || "http://localhost:3001";
     if (config.bearerToken) {
       this.authStrategy = new BearerAuth(config.bearerToken);
     } else if (config.apiKey) {
@@ -504,7 +532,7 @@ var Timbrix = class {
       },
       hooks: {
         beforeRequest: [
-          (request) => {
+          ({ request }) => {
             if (this.authStrategy) {
               const authHeaders = this.authStrategy.getHeaders();
               Object.entries(authHeaders).forEach(([key, value]) => {
@@ -524,6 +552,7 @@ var Timbrix = class {
     this.oauth = new OAuthResource(this.http);
     this.products = new ProductsResource(this.http);
     this.sat = new SatResource(this.http);
+    this.invoices = new InvoicesResource(this.http);
   }
   /**
    * Update authentication strategy (useful for CLI when token changes)
@@ -550,6 +579,7 @@ export {
   AuthResource,
   BearerAuth,
   CustomersResource,
+  InvoicesResource,
   OAuthResource,
   OrganizationsResource,
   ProductsResource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timbrix/sdk",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "TypeScript SDK for Timbrix API",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -27,12 +27,12 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "ky": "^1.14.3"
+    "ky": "^2.0.2"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "@repo/eslint-config": "0.1.0",
+    "typescript": "^6.0.3",
+    "@repo/eslint-config": "0.1.1",
     "@repo/typescript-config": "0.1.0"
   },
   "scripts": {