factuplan 0.2.1 → 0.4.1

package/README.md

@@ -129,6 +129,58 @@ const { url } = await factuplan.invoices.downloadXml('invoice-id');
 const { url } = await factuplan.invoices.downloadPdf('invoice-id');
 ```
 
+### Firmar y autorizar XML (Modo B)
+
+Si ya tienes tu XML generado (sin firmar), puedes enviarlo para que Factuplan lo firme con tu certificado y lo autorice ante el SRI:
+
+```typescript
+import { readFileSync } from 'fs';
+
+// Leer XML sin firmar
+const xml = readFileSync('./factura.xml', 'utf-8');
+
+// Firmar y autorizar
+const result = await factuplan.invoices.signAndAuthorize({ xml });
+
+console.log(result.accessKey); // Clave de acceso SRI
+console.log(result.status);    // Estado del comprobante
+
+// Consultar estado de autorizacion
+const status = await factuplan.invoices.getStatus(result.id);
+
+// Descargar XML autorizado
+const { url } = await factuplan.invoices.downloadXml(result.id);
+```
+
+### Solo firmar XML (Modo C)
+
+Firma el XML con tu certificado sin enviarlo al SRI:
+
+```typescript
+const { signedXml } = await factuplan.invoices.signOnly({ xml });
+```
+
+### Validar XML
+
+Valida la estructura de un XML sin procesarlo:
+
+```typescript
+const { valid, errors } = await factuplan.invoices.validateXml({ xml });
+if (!valid) {
+  console.log('Errores:', errors);
+}
+```
+
+### Verificar autorizacion
+
+Consulta el estado de autorizacion de un comprobante por su clave de acceso:
+
+```typescript
+const result = await factuplan.invoices.verify('0104202601099337815000110010010000000011234567890');
+console.log(result.authorized);           // true/false
+console.log(result.authorizationNumber);   // Numero de autorizacion
+```
+
 ### Uso y certificado
 
 ```typescript

package/dist/index.d.mts

@@ -133,6 +133,39 @@ interface DownloadUrlResponse {
     url: string;
     s3Key?: string;
 }
+interface SignAndAuthorizeInput {
+    /** Unsigned XML string */
+    xml: string;
+}
+interface SignAndAuthorizeResponse {
+    id: string;
+    accessKey: string;
+    status: string;
+}
+interface SignOnlyInput {
+    /** Unsigned XML string */
+    xml: string;
+}
+interface SignOnlyResponse {
+    signedXml: string;
+}
+interface ValidateXmlInput {
+    /** XML string to validate */
+    xml: string;
+}
+interface ValidateXmlResponse {
+    valid: boolean;
+    errors: string[];
+}
+interface VerifyResponse {
+    authorized: boolean;
+    authorizationNumber?: string;
+    authorizationDate?: string;
+    messages?: Array<{
+        code?: string;
+        message?: string;
+    }>;
+}
 interface UsageResponse {
     apiKeyId: string;
     month: string;
@@ -149,6 +182,24 @@ interface CertificateStatus {
     legalName?: string;
     expiresAt?: string;
 }
+interface WebhookEvent {
+    id: string;
+    event: string;
+    timestamp: string;
+    data: WebhookReceiptData;
+    webhookId: string;
+    attempt: number;
+}
+interface WebhookReceiptData {
+    receiptId: string;
+    type: string;
+    accessKey: string;
+    authorizationNumber: string;
+    documentNumber: string;
+    total: string;
+    customerName: string;
+    customerIdentification: string;
+}
 interface FactuplanOptions {
     /** Base URL of the API (default: https://api.factuplan.com/api/v1) */
     baseUrl?: string;
@@ -156,10 +207,10 @@ interface FactuplanOptions {
     timeout?: number;
 }
 
-type Requester$2 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+type Requester$3 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class CustomersResource {
     private request;
-    constructor(request: Requester$2);
+    constructor(request: Requester$3);
     create(input: CreateCustomerInput): Promise<Customer>;
     list(params?: CustomerListParams): Promise<PaginatedResponse<Customer>>;
     get(id: string): Promise<Customer>;
@@ -167,21 +218,25 @@ declare class CustomersResource {
     delete(id: string): Promise<void>;
 }
 
-type Requester$1 = (method: string, path: string, body?: unknown) => Promise<unknown>;
+type Requester$2 = (method: string, path: string, body?: unknown) => Promise<unknown>;
 declare class InvoicesResource {
     private request;
-    constructor(request: Requester$1);
+    constructor(request: Requester$2);
     create(input: CreateInvoiceInput): Promise<Invoice>;
+    signAndAuthorize(input: SignAndAuthorizeInput): Promise<SignAndAuthorizeResponse>;
+    signOnly(input: SignOnlyInput): Promise<SignOnlyResponse>;
+    validateXml(input: ValidateXmlInput): Promise<ValidateXmlResponse>;
+    verify(accessKey: string): Promise<VerifyResponse>;
     get(id: string): Promise<Record<string, unknown>>;
     getStatus(id: string): Promise<InvoiceStatus>;
     downloadXml(id: string): Promise<DownloadUrlResponse>;
     downloadPdf(id: string): Promise<DownloadUrlResponse>;
 }
 
-type Requester = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+type Requester$1 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class ProductsResource {
     private request;
-    constructor(request: Requester);
+    constructor(request: Requester$1);
     create(input: CreateProductInput): Promise<Product>;
     list(params?: ProductListParams): Promise<PaginatedResponse<Product>>;
     get(id: string): Promise<Product>;
@@ -189,6 +244,20 @@ declare class ProductsResource {
     delete(id: string): Promise<void>;
 }
 
+type Requester = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+declare class WebhooksResource {
+    private readonly request;
+    constructor(requester: Requester);
+    /**
+     * Verify that a receipt (document) exists in the API.
+     * This is a second layer of verification beyond signature checking.
+     *
+     * @param receiptId - The receipt ID from the webhook payload
+     * @returns The receipt object if it exists, or `null` if not found
+     */
+    verifyReceipt(receiptId: string): Promise<Record<string, unknown> | null>;
+}
+
 declare class Factuplan {
     private readonly apiKey;
     private readonly baseUrl;
@@ -196,6 +265,8 @@ declare class Factuplan {
     readonly customers: CustomersResource;
     readonly products: ProductsResource;
     readonly invoices: InvoicesResource;
+    readonly webhooks: WebhooksResource;
+    static readonly webhooks: typeof WebhooksResource;
     constructor(apiKey: string, options?: FactuplanOptions);
     usage(): Promise<UsageResponse>;
     certificateStatus(): Promise<CertificateStatus>;
@@ -215,4 +286,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 Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, RateLimitError, type UpdateCustomerInput, type UpdateProductInput, type UsageResponse };
+export { AuthenticationError, type CertificateStatus, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, 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 };

package/dist/index.d.ts

@@ -133,6 +133,39 @@ interface DownloadUrlResponse {
     url: string;
     s3Key?: string;
 }
+interface SignAndAuthorizeInput {
+    /** Unsigned XML string */
+    xml: string;
+}
+interface SignAndAuthorizeResponse {
+    id: string;
+    accessKey: string;
+    status: string;
+}
+interface SignOnlyInput {
+    /** Unsigned XML string */
+    xml: string;
+}
+interface SignOnlyResponse {
+    signedXml: string;
+}
+interface ValidateXmlInput {
+    /** XML string to validate */
+    xml: string;
+}
+interface ValidateXmlResponse {
+    valid: boolean;
+    errors: string[];
+}
+interface VerifyResponse {
+    authorized: boolean;
+    authorizationNumber?: string;
+    authorizationDate?: string;
+    messages?: Array<{
+        code?: string;
+        message?: string;
+    }>;
+}
 interface UsageResponse {
     apiKeyId: string;
     month: string;
@@ -149,6 +182,24 @@ interface CertificateStatus {
     legalName?: string;
     expiresAt?: string;
 }
+interface WebhookEvent {
+    id: string;
+    event: string;
+    timestamp: string;
+    data: WebhookReceiptData;
+    webhookId: string;
+    attempt: number;
+}
+interface WebhookReceiptData {
+    receiptId: string;
+    type: string;
+    accessKey: string;
+    authorizationNumber: string;
+    documentNumber: string;
+    total: string;
+    customerName: string;
+    customerIdentification: string;
+}
 interface FactuplanOptions {
     /** Base URL of the API (default: https://api.factuplan.com/api/v1) */
     baseUrl?: string;
@@ -156,10 +207,10 @@ interface FactuplanOptions {
     timeout?: number;
 }
 
-type Requester$2 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+type Requester$3 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class CustomersResource {
     private request;
-    constructor(request: Requester$2);
+    constructor(request: Requester$3);
     create(input: CreateCustomerInput): Promise<Customer>;
     list(params?: CustomerListParams): Promise<PaginatedResponse<Customer>>;
     get(id: string): Promise<Customer>;
@@ -167,21 +218,25 @@ declare class CustomersResource {
     delete(id: string): Promise<void>;
 }
 
-type Requester$1 = (method: string, path: string, body?: unknown) => Promise<unknown>;
+type Requester$2 = (method: string, path: string, body?: unknown) => Promise<unknown>;
 declare class InvoicesResource {
     private request;
-    constructor(request: Requester$1);
+    constructor(request: Requester$2);
     create(input: CreateInvoiceInput): Promise<Invoice>;
+    signAndAuthorize(input: SignAndAuthorizeInput): Promise<SignAndAuthorizeResponse>;
+    signOnly(input: SignOnlyInput): Promise<SignOnlyResponse>;
+    validateXml(input: ValidateXmlInput): Promise<ValidateXmlResponse>;
+    verify(accessKey: string): Promise<VerifyResponse>;
     get(id: string): Promise<Record<string, unknown>>;
     getStatus(id: string): Promise<InvoiceStatus>;
     downloadXml(id: string): Promise<DownloadUrlResponse>;
     downloadPdf(id: string): Promise<DownloadUrlResponse>;
 }
 
-type Requester = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+type Requester$1 = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
 declare class ProductsResource {
     private request;
-    constructor(request: Requester);
+    constructor(request: Requester$1);
     create(input: CreateProductInput): Promise<Product>;
     list(params?: ProductListParams): Promise<PaginatedResponse<Product>>;
     get(id: string): Promise<Product>;
@@ -189,6 +244,20 @@ declare class ProductsResource {
     delete(id: string): Promise<void>;
 }
 
+type Requester = (method: string, path: string, body?: unknown, params?: Record<string, string | number | undefined>) => Promise<unknown>;
+declare class WebhooksResource {
+    private readonly request;
+    constructor(requester: Requester);
+    /**
+     * Verify that a receipt (document) exists in the API.
+     * This is a second layer of verification beyond signature checking.
+     *
+     * @param receiptId - The receipt ID from the webhook payload
+     * @returns The receipt object if it exists, or `null` if not found
+     */
+    verifyReceipt(receiptId: string): Promise<Record<string, unknown> | null>;
+}
+
 declare class Factuplan {
     private readonly apiKey;
     private readonly baseUrl;
@@ -196,6 +265,8 @@ declare class Factuplan {
     readonly customers: CustomersResource;
     readonly products: ProductsResource;
     readonly invoices: InvoicesResource;
+    readonly webhooks: WebhooksResource;
+    static readonly webhooks: typeof WebhooksResource;
     constructor(apiKey: string, options?: FactuplanOptions);
     usage(): Promise<UsageResponse>;
     certificateStatus(): Promise<CertificateStatus>;
@@ -215,4 +286,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 Invoice, type InvoiceCustomer, type InvoiceItem, type InvoiceStatus, type PaginatedResponse, type Product, type ProductListParams, RateLimitError, type UpdateCustomerInput, type UpdateProductInput, type UsageResponse };
+export { AuthenticationError, type CertificateStatus, type CreateCustomerInput, type CreateInvoiceInput, type CreateProductInput, type Customer, type CustomerListParams, type DownloadUrlResponse, Factuplan, FactuplanError, type FactuplanOptions, 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 };

package/dist/index.js

@@ -80,6 +80,18 @@ var InvoicesResource = class {
   async create(input) {
     return this.request("POST", "/developer/invoices", input);
   }
+  async signAndAuthorize(input) {
+    return this.request("POST", "/developer/sign-and-authorize", input);
+  }
+  async signOnly(input) {
+    return this.request("POST", "/developer/sign", input);
+  }
+  async validateXml(input) {
+    return this.request("POST", "/developer/validate-xml", input);
+  }
+  async verify(accessKey) {
+    return this.request("GET", `/developer/verify/${accessKey}`);
+  }
   async get(id) {
     return this.request("GET", `/developer/receipts/${id}`);
   }
@@ -116,6 +128,28 @@ var ProductsResource = class {
   }
 };
 
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(requester) {
+    this.request = requester;
+  }
+  /**
+   * Verify that a receipt (document) exists in the API.
+   * This is a second layer of verification beyond signature checking.
+   *
+   * @param receiptId - The receipt ID from the webhook payload
+   * @returns The receipt object if it exists, or `null` if not found
+   */
+  async verifyReceipt(receiptId) {
+    try {
+      const result = await this.request("GET", `/developer/receipts/${receiptId}`);
+      return result ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api-rest.factuplan.com.ec/api/v1";
 var DEFAULT_TIMEOUT = 3e4;
@@ -129,6 +163,7 @@ var Factuplan = class {
     this.customers = new CustomersResource(requester);
     this.products = new ProductsResource(requester);
     this.invoices = new InvoicesResource(requester);
+    this.webhooks = new WebhooksResource(requester);
   }
   async usage() {
     return this.request("GET", "/developer/usage");
@@ -182,6 +217,7 @@ var Factuplan = class {
     return json;
   }
 };
+Factuplan.webhooks = WebhooksResource;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,

package/dist/index.mjs

@@ -51,6 +51,18 @@ var InvoicesResource = class {
   async create(input) {
     return this.request("POST", "/developer/invoices", input);
   }
+  async signAndAuthorize(input) {
+    return this.request("POST", "/developer/sign-and-authorize", input);
+  }
+  async signOnly(input) {
+    return this.request("POST", "/developer/sign", input);
+  }
+  async validateXml(input) {
+    return this.request("POST", "/developer/validate-xml", input);
+  }
+  async verify(accessKey) {
+    return this.request("GET", `/developer/verify/${accessKey}`);
+  }
   async get(id) {
     return this.request("GET", `/developer/receipts/${id}`);
   }
@@ -87,6 +99,28 @@ var ProductsResource = class {
   }
 };
 
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(requester) {
+    this.request = requester;
+  }
+  /**
+   * Verify that a receipt (document) exists in the API.
+   * This is a second layer of verification beyond signature checking.
+   *
+   * @param receiptId - The receipt ID from the webhook payload
+   * @returns The receipt object if it exists, or `null` if not found
+   */
+  async verifyReceipt(receiptId) {
+    try {
+      const result = await this.request("GET", `/developer/receipts/${receiptId}`);
+      return result ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api-rest.factuplan.com.ec/api/v1";
 var DEFAULT_TIMEOUT = 3e4;
@@ -100,6 +134,7 @@ var Factuplan = class {
     this.customers = new CustomersResource(requester);
     this.products = new ProductsResource(requester);
     this.invoices = new InvoicesResource(requester);
+    this.webhooks = new WebhooksResource(requester);
   }
   async usage() {
     return this.request("GET", "/developer/usage");
@@ -153,6 +188,7 @@ var Factuplan = class {
     return json;
   }
 };
+Factuplan.webhooks = WebhooksResource;
 export {
   AuthenticationError,
   Factuplan,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "factuplan",
-  "version": "0.2.1",
+  "version": "0.4.1",
   "description": "Official Factuplan SDK for JavaScript & TypeScript — Create electronic invoices for Ecuador (SRI)",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -16,6 +16,7 @@
     "dist"
   ],
   "devDependencies": {
+    "@types/node": "^25.6.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0"
   },