factuplan 0.7.0 → 0.10.0

package/dist/index.d.mts

@@ -122,6 +122,11 @@ interface CreateInvoiceInput {
     /** List of payment methods for multi-payment support. */
     payments?: InvoicePayment[];
     additionalInfo?: Record<string, string>;
+    /**
+     * Whether to send the authorized invoice by email to the customer.
+     * @default true
+     */
+    sendEmail?: boolean;
 }
 interface ImportByAccessKeyInput {
     /** 49-digit SRI access key (claveAcceso) of an already-authorized invoice */
@@ -217,11 +222,40 @@ interface WebhookReceiptData {
     customerName: string;
     customerIdentification: string;
 }
+interface VoidInvoiceResponse {
+    id: string;
+    status: string;
+    accessKey: string | null;
+    voidReason: string;
+    message: string;
+}
+interface UpdateSequentialResponse {
+    branchCode: string;
+    emissionCode: string;
+    invoiceSequential: number;
+    updatedAt: string;
+}
+interface CertificateUploadResponse {
+    hasCertificate: boolean;
+    isExpired?: boolean;
+    daysUntilExpiry?: number | null;
+    ruc?: string;
+    legalName?: string;
+    expiresAt?: string;
+    /** True if a new contribuyente was automatically created from the certificate data */
+    created?: boolean;
+}
 interface FactuplanOptions {
     /** Base URL of the API (default: https://api-rest.factuplan.com.ec/v1) */
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /**
+     * Default taxpayer RUC sent as `x-taxpayer-ruc` header in every request.
+     * Required for most operations (emit, sign, customers, products, etc.).
+     * Not required for `queryExternalByAccessKey`.
+     */
+    ruc?: string;
 }
 interface QueryExternalByAccessKeyInput {
     /** Clave de acceso de 49 dígitos del comprobante en el SRI */
@@ -248,6 +282,26 @@ interface QueryExternalByAccessKeyResponse {
     xmlBase64: string;
 }
 
+type Requester$4 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+declare class CertificatesResource {
+    private request;
+    constructor(request: Requester$4);
+    /**
+     * Get the certificate status for the current taxpayer (requires x-taxpayer-ruc header).
+     */
+    status(): Promise<CertificateStatus>;
+    /**
+     * Upload a P12 certificate.
+     * If the RUC in the certificate does not yet exist as a contribuyente in your
+     * workspace and your plan allows it, the contribuyente is created automatically
+     * and linked to your API key.
+     *
+     * @param file - P12 file as a Uint8Array/Buffer (Node.js) or Blob (browser)
+     * @param password - Password for the P12 file
+     */
+    upload(file: Uint8Array | Blob, password: string): Promise<CertificateUploadResponse>;
+}
+
 type Requester$3 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class CustomersResource {
     private request;
@@ -274,6 +328,8 @@ declare class InvoicesResource {
     downloadPdf(id: string): Promise<DownloadUrlResponse>;
     importByAccessKey(input: ImportByAccessKeyInput): Promise<Invoice>;
     queryExternalByAccessKey(input: QueryExternalByAccessKeyInput): Promise<QueryExternalByAccessKeyResponse>;
+    void(id: string, reason: string): Promise<VoidInvoiceResponse>;
+    updateSequential(branchCode: string, emissionCode: string, invoiceSequential: number): Promise<UpdateSequentialResponse>;
 }
 
 type Requester$1 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
@@ -305,6 +361,8 @@ declare class Factuplan {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly options;
+    readonly certificates: CertificatesResource;
     readonly customers: CustomersResource;
     readonly products: ProductsResource;
     readonly invoices: InvoicesResource;
@@ -312,7 +370,6 @@ declare class Factuplan {
     static readonly webhooks: typeof WebhooksResource;
     constructor(apiKey: string, options?: FactuplanOptions);
     usage(): Promise<UsageResponse>;
-    certificateStatus(): Promise<CertificateStatus>;
     private request;
 }
 
@@ -329,4 +386,4 @@ declare class RateLimitError extends FactuplanError {
     constructor(message?: string);
 }
 
-export { AuthenticationError, type CertificateStatus, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, type ImportByAccessKeyInput, type Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, RateLimitError, type SignAndAuthorizeInput, type SignAndAuthorizeResponse, type SignOnlyInput, type SignOnlyResponse, type UpdateCustomerInput, type UpdateProductInput, type UsageResponse, type ValidateXmlInput, type ValidateXmlResponse, type VerifyResponse, type WebhookEvent, type WebhookReceiptData };
+export { AuthenticationError, type CertificateStatus, type CertificateUploadResponse, CertificatesResource, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, type ImportByAccessKeyInput, type Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, type QueryExternalByAccessKeyInput, type QueryExternalByAccessKeyResponse, RateLimitError, type SignAndAuthorizeInput, type SignAndAuthorizeResponse, type SignOnlyInput, type SignOnlyResponse, type UpdateCustomerInput, type UpdateProductInput, type UpdateSequentialResponse, type UsageResponse, type ValidateXmlInput, type ValidateXmlResponse, type VerifyResponse, type VoidInvoiceResponse, type WebhookEvent, type WebhookReceiptData };

package/dist/index.d.ts

@@ -122,6 +122,11 @@ interface CreateInvoiceInput {
     /** List of payment methods for multi-payment support. */
     payments?: InvoicePayment[];
     additionalInfo?: Record<string, string>;
+    /**
+     * Whether to send the authorized invoice by email to the customer.
+     * @default true
+     */
+    sendEmail?: boolean;
 }
 interface ImportByAccessKeyInput {
     /** 49-digit SRI access key (claveAcceso) of an already-authorized invoice */
@@ -217,11 +222,40 @@ interface WebhookReceiptData {
     customerName: string;
     customerIdentification: string;
 }
+interface VoidInvoiceResponse {
+    id: string;
+    status: string;
+    accessKey: string | null;
+    voidReason: string;
+    message: string;
+}
+interface UpdateSequentialResponse {
+    branchCode: string;
+    emissionCode: string;
+    invoiceSequential: number;
+    updatedAt: string;
+}
+interface CertificateUploadResponse {
+    hasCertificate: boolean;
+    isExpired?: boolean;
+    daysUntilExpiry?: number | null;
+    ruc?: string;
+    legalName?: string;
+    expiresAt?: string;
+    /** True if a new contribuyente was automatically created from the certificate data */
+    created?: boolean;
+}
 interface FactuplanOptions {
     /** Base URL of the API (default: https://api-rest.factuplan.com.ec/v1) */
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /**
+     * Default taxpayer RUC sent as `x-taxpayer-ruc` header in every request.
+     * Required for most operations (emit, sign, customers, products, etc.).
+     * Not required for `queryExternalByAccessKey`.
+     */
+    ruc?: string;
 }
 interface QueryExternalByAccessKeyInput {
     /** Clave de acceso de 49 dígitos del comprobante en el SRI */
@@ -248,6 +282,26 @@ interface QueryExternalByAccessKeyResponse {
     xmlBase64: string;
 }
 
+type Requester$4 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+declare class CertificatesResource {
+    private request;
+    constructor(request: Requester$4);
+    /**
+     * Get the certificate status for the current taxpayer (requires x-taxpayer-ruc header).
+     */
+    status(): Promise<CertificateStatus>;
+    /**
+     * Upload a P12 certificate.
+     * If the RUC in the certificate does not yet exist as a contribuyente in your
+     * workspace and your plan allows it, the contribuyente is created automatically
+     * and linked to your API key.
+     *
+     * @param file - P12 file as a Uint8Array/Buffer (Node.js) or Blob (browser)
+     * @param password - Password for the P12 file
+     */
+    upload(file: Uint8Array | Blob, password: string): Promise<CertificateUploadResponse>;
+}
+
 type Requester$3 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class CustomersResource {
     private request;
@@ -274,6 +328,8 @@ declare class InvoicesResource {
     downloadPdf(id: string): Promise<DownloadUrlResponse>;
     importByAccessKey(input: ImportByAccessKeyInput): Promise<Invoice>;
     queryExternalByAccessKey(input: QueryExternalByAccessKeyInput): Promise<QueryExternalByAccessKeyResponse>;
+    void(id: string, reason: string): Promise<VoidInvoiceResponse>;
+    updateSequential(branchCode: string, emissionCode: string, invoiceSequential: number): Promise<UpdateSequentialResponse>;
 }
 
 type Requester$1 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
@@ -305,6 +361,8 @@ declare class Factuplan {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly options;
+    readonly certificates: CertificatesResource;
     readonly customers: CustomersResource;
     readonly products: ProductsResource;
     readonly invoices: InvoicesResource;
@@ -312,7 +370,6 @@ declare class Factuplan {
     static readonly webhooks: typeof WebhooksResource;
     constructor(apiKey: string, options?: FactuplanOptions);
     usage(): Promise<UsageResponse>;
-    certificateStatus(): Promise<CertificateStatus>;
     private request;
 }
 
@@ -329,4 +386,4 @@ declare class RateLimitError extends FactuplanError {
     constructor(message?: string);
 }
 
-export { AuthenticationError, type CertificateStatus, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, type ImportByAccessKeyInput, type Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, RateLimitError, type SignAndAuthorizeInput, type SignAndAuthorizeResponse, type SignOnlyInput, type SignOnlyResponse, type UpdateCustomerInput, type UpdateProductInput, type UsageResponse, type ValidateXmlInput, type ValidateXmlResponse, type VerifyResponse, type WebhookEvent, type WebhookReceiptData };
+export { AuthenticationError, type CertificateStatus, type CertificateUploadResponse, CertificatesResource, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, type ImportByAccessKeyInput, type Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, type QueryExternalByAccessKeyInput, type QueryExternalByAccessKeyResponse, RateLimitError, type SignAndAuthorizeInput, type SignAndAuthorizeResponse, type SignOnlyInput, type SignOnlyResponse, type UpdateCustomerInput, type UpdateProductInput, type UpdateSequentialResponse, type UsageResponse, type ValidateXmlInput, type ValidateXmlResponse, type VerifyResponse, type VoidInvoiceResponse, type WebhookEvent, type WebhookReceiptData };

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
+  CertificatesResource: () => CertificatesResource,
   Factuplan: () => Factuplan,
   FactuplanError: () => FactuplanError,
   RateLimitError: () => RateLimitError
@@ -50,6 +51,35 @@ var RateLimitError = class extends FactuplanError {
   }
 };
 
+// src/resources/certificates.ts
+var CertificatesResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Get the certificate status for the current taxpayer (requires x-taxpayer-ruc header).
+   */
+  async status() {
+    return this.request("GET", "/developer/certificate/status");
+  }
+  /**
+   * Upload a P12 certificate.
+   * If the RUC in the certificate does not yet exist as a contribuyente in your
+   * workspace and your plan allows it, the contribuyente is created automatically
+   * and linked to your API key.
+   *
+   * @param file - P12 file as a Uint8Array/Buffer (Node.js) or Blob (browser)
+   * @param password - Password for the P12 file
+   */
+  async upload(file, password) {
+    return this.request(
+      "POST",
+      "/developer/certificate",
+      { __formData: true, file, password }
+    );
+  }
+};
+
 // src/resources/customers.ts
 var CustomersResource = class {
   constructor(request) {
@@ -114,6 +144,20 @@ var InvoicesResource = class {
       input
     );
   }
+  async void(id, reason) {
+    return this.request(
+      "POST",
+      `/developer/receipts/${id}/void`,
+      { reason }
+    );
+  }
+  async updateSequential(branchCode, emissionCode, invoiceSequential) {
+    return this.request(
+      "PATCH",
+      "/developer/invoices/sequential",
+      { branchCode, emissionCode, invoiceSequential }
+    );
+  }
 };
 
 // src/resources/products.ts
@@ -167,9 +211,11 @@ var Factuplan = class {
   constructor(apiKey, options) {
     if (!apiKey) throw new Error("API key is required");
     this.apiKey = apiKey;
+    this.options = options;
     this.baseUrl = (options?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeout = options?.timeout ?? DEFAULT_TIMEOUT;
     const requester = this.request.bind(this);
+    this.certificates = new CertificatesResource(requester);
     this.customers = new CustomersResource(requester);
     this.products = new ProductsResource(requester);
     this.invoices = new InvoicesResource(requester);
@@ -178,9 +224,6 @@ var Factuplan = class {
   async usage() {
     return this.request("GET", "/developer/usage");
   }
-  async certificateStatus() {
-    return this.request("GET", "/developer/certificate/status");
-  }
   async request(method, path, body, params) {
     let url = `${this.baseUrl}${path}`;
     if (params) {
@@ -197,13 +240,27 @@ var Factuplan = class {
       "x-api-key": this.apiKey,
       Accept: "application/json"
     };
+    if (this.options?.ruc) {
+      headers["x-taxpayer-ruc"] = this.options.ruc;
+    }
+    let fetchBody;
     if (body !== void 0) {
-      headers["Content-Type"] = "application/json";
+      if (body !== null && typeof body === "object" && body.__formData === true) {
+        const { file, password } = body;
+        const fd = new FormData();
+        const blob = file instanceof Blob ? file : new Blob([file]);
+        fd.append("file", blob, "certificate.p12");
+        fd.append("password", password);
+        fetchBody = fd;
+      } else {
+        headers["Content-Type"] = "application/json";
+        fetchBody = JSON.stringify(body);
+      }
     }
     const response = await fetch(url, {
       method,
       headers,
-      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      body: fetchBody,
       signal: AbortSignal.timeout(this.timeout)
     });
     if (response.status === 204) return void 0;
@@ -231,6 +288,7 @@ Factuplan.webhooks = WebhooksResource;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,
+  CertificatesResource,
   Factuplan,
   FactuplanError,
   RateLimitError

package/dist/index.mjs

@@ -21,6 +21,35 @@ var RateLimitError = class extends FactuplanError {
   }
 };
 
+// src/resources/certificates.ts
+var CertificatesResource = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Get the certificate status for the current taxpayer (requires x-taxpayer-ruc header).
+   */
+  async status() {
+    return this.request("GET", "/developer/certificate/status");
+  }
+  /**
+   * Upload a P12 certificate.
+   * If the RUC in the certificate does not yet exist as a contribuyente in your
+   * workspace and your plan allows it, the contribuyente is created automatically
+   * and linked to your API key.
+   *
+   * @param file - P12 file as a Uint8Array/Buffer (Node.js) or Blob (browser)
+   * @param password - Password for the P12 file
+   */
+  async upload(file, password) {
+    return this.request(
+      "POST",
+      "/developer/certificate",
+      { __formData: true, file, password }
+    );
+  }
+};
+
 // src/resources/customers.ts
 var CustomersResource = class {
   constructor(request) {
@@ -85,6 +114,20 @@ var InvoicesResource = class {
       input
     );
   }
+  async void(id, reason) {
+    return this.request(
+      "POST",
+      `/developer/receipts/${id}/void`,
+      { reason }
+    );
+  }
+  async updateSequential(branchCode, emissionCode, invoiceSequential) {
+    return this.request(
+      "PATCH",
+      "/developer/invoices/sequential",
+      { branchCode, emissionCode, invoiceSequential }
+    );
+  }
 };
 
 // src/resources/products.ts
@@ -138,9 +181,11 @@ var Factuplan = class {
   constructor(apiKey, options) {
     if (!apiKey) throw new Error("API key is required");
     this.apiKey = apiKey;
+    this.options = options;
     this.baseUrl = (options?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeout = options?.timeout ?? DEFAULT_TIMEOUT;
     const requester = this.request.bind(this);
+    this.certificates = new CertificatesResource(requester);
     this.customers = new CustomersResource(requester);
     this.products = new ProductsResource(requester);
     this.invoices = new InvoicesResource(requester);
@@ -149,9 +194,6 @@ var Factuplan = class {
   async usage() {
     return this.request("GET", "/developer/usage");
   }
-  async certificateStatus() {
-    return this.request("GET", "/developer/certificate/status");
-  }
   async request(method, path, body, params) {
     let url = `${this.baseUrl}${path}`;
     if (params) {
@@ -168,13 +210,27 @@ var Factuplan = class {
       "x-api-key": this.apiKey,
       Accept: "application/json"
     };
+    if (this.options?.ruc) {
+      headers["x-taxpayer-ruc"] = this.options.ruc;
+    }
+    let fetchBody;
     if (body !== void 0) {
-      headers["Content-Type"] = "application/json";
+      if (body !== null && typeof body === "object" && body.__formData === true) {
+        const { file, password } = body;
+        const fd = new FormData();
+        const blob = file instanceof Blob ? file : new Blob([file]);
+        fd.append("file", blob, "certificate.p12");
+        fd.append("password", password);
+        fetchBody = fd;
+      } else {
+        headers["Content-Type"] = "application/json";
+        fetchBody = JSON.stringify(body);
+      }
     }
     const response = await fetch(url, {
       method,
       headers,
-      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      body: fetchBody,
       signal: AbortSignal.timeout(this.timeout)
     });
     if (response.status === 204) return void 0;
@@ -201,6 +257,7 @@ var Factuplan = class {
 Factuplan.webhooks = WebhooksResource;
 export {
   AuthenticationError,
+  CertificatesResource,
   Factuplan,
   FactuplanError,
   RateLimitError

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "factuplan",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "Official Factuplan SDK for JavaScript & TypeScript — Create electronic invoices for Ecuador (SRI)",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",