@epostak/sdk 1.0.0 → 1.1.0

package/dist/resources/firms.js

@@ -1,12 +1,67 @@
 import { BaseResource, buildQuery } from "../utils/request.js";
+/**
+ * Resource for managing firms (companies) associated with your account.
+ * Integrators use this to assign client firms, view their documents,
+ * and register Peppol identifiers.
+ *
+ * @example
+ * ```typescript
+ * // List all managed firms
+ * const firms = await client.firms.list();
+ *
+ * // Assign a new firm by ICO
+ * const { firm } = await client.firms.assign({ ico: '12345678' });
+ * ```
+ */
 export class FirmsResource extends BaseResource {
+    /**
+     * List all firms associated with the current account.
+     * For integrator keys, returns all assigned client firms.
+     *
+     * @returns Array of firm summaries
+     *
+     * @example
+     * ```typescript
+     * const firms = await client.firms.list();
+     * firms.forEach(f => console.log(f.name, f.peppolStatus));
+     * ```
+     */
     async list() {
         const res = await this.request("GET", "/firms");
         return res.firms;
     }
+    /**
+     * Get detailed information about a specific firm, including tax IDs,
+     * address, and all registered Peppol identifiers.
+     *
+     * @param id - Firm UUID
+     * @returns Detailed firm information
+     *
+     * @example
+     * ```typescript
+     * const firm = await client.firms.get('firm-uuid');
+     * console.log(firm.icDph); // "SK2020123456"
+     * ```
+     */
     get(id) {
         return this.request("GET", `/firms/${encodeURIComponent(id)}`);
     }
+    /**
+     * List documents belonging to a specific firm.
+     * Useful for integrators to view a client's document history.
+     *
+     * @param id - Firm UUID
+     * @param params - Optional pagination and direction filter
+     * @returns Paginated list of the firm's documents
+     *
+     * @example
+     * ```typescript
+     * const { documents } = await client.firms.documents('firm-uuid', {
+     *   direction: 'inbound',
+     *   limit: 100,
+     * });
+     * ```
+     */
     documents(id, params) {
         return this.request("GET", `/firms/${encodeURIComponent(id)}/documents${buildQuery({
             offset: params?.offset,
@@ -14,12 +69,61 @@ export class FirmsResource extends BaseResource {
             direction: params?.direction,
         })}`);
     }
+    /**
+     * Register a new Peppol identifier for a firm. This enables the firm
+     * to send and receive documents on the Peppol network under this identifier.
+     *
+     * @param id - Firm UUID
+     * @param peppolId - Peppol identifier with scheme and value
+     * @returns The registered identifier details
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firms.registerPeppolId('firm-uuid', {
+     *   scheme: '0245',
+     *   identifier: '1234567890',
+     * });
+     * console.log(result.peppolId); // "0245:1234567890"
+     * ```
+     */
     registerPeppolId(id, peppolId) {
         return this.request("POST", `/firms/${encodeURIComponent(id)}/peppol-identifiers`, peppolId);
     }
+    /**
+     * Assign a firm to the integrator account by its Slovak ICO.
+     * Once assigned, you can send/receive documents on behalf of this firm.
+     *
+     * @param body - Request containing the firm's ICO (8-digit Slovak business registration number)
+     * @returns The assigned firm details and status
+     *
+     * @example
+     * ```typescript
+     * const { firm } = await client.firms.assign({ ico: '12345678' });
+     * console.log(firm.id); // Use this UUID for subsequent operations
+     * ```
+     */
     assign(body) {
         return this.request("POST", "/firms/assign", body);
     }
+    /**
+     * Assign multiple firms at once by their Slovak ICOs.
+     * Each ICO is processed independently — individual failures don't affect others.
+     * Maximum 50 ICOs per request.
+     *
+     * @param body - Request containing an array of ICOs
+     * @returns Individual results for each ICO (success or error)
+     *
+     * @example
+     * ```typescript
+     * const { results } = await client.firms.assignBatch({
+     *   icos: ['12345678', '87654321', '11223344'],
+     * });
+     * results.forEach(r => {
+     *   if (r.error) console.error(`${r.ico}: ${r.message}`);
+     *   else console.log(`${r.ico}: ${r.status}`);
+     * });
+     * ```
+     */
     assignBatch(body) {
         return this.request("POST", "/firms/assign/batch", body);
     }

package/dist/resources/firms.js.map

@@ -1 +1 @@
-{"version":3,"file":"firms.js","sourceRoot":"","sources":["../../src/resources/firms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAc/D,MAAM,OAAO,aAAc,SAAQ,YAAY;IAC7C,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAoB,KAAK,EAAE,QAAQ,CAAC,CAAC;QACnE,OAAO,GAAG,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,SAAS,CACP,EAAU,EACV,MAA4B;QAE5B,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,UAAU,kBAAkB,CAAC,EAAE,CAAC,aAAa,UAAU,CAAC;YACtD,MAAM,EAAE,MAAM,EAAE,MAAM;YACtB,KAAK,EAAE,MAAM,EAAE,KAAK;YACpB,SAAS,EAAE,MAAM,EAAE,SAAS;SAC7B,CAAC,EAAE,CACL,CAAC;IACJ,CAAC;IAED,gBAAgB,CACd,EAAU,EACV,QAAgD;QAEhD,OAAO,IAAI,CAAC,OAAO,CACjB,MAAM,EACN,UAAU,kBAAkB,CAAC,EAAE,CAAC,qBAAqB,EACrD,QAAQ,CACT,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,IAAuB;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,CAAC;IACrD,CAAC;IAED,WAAW,CACT,IAA6B;QAE7B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,qBAAqB,EAAE,IAAI,CAAC,CAAC;IAC3D,CAAC;CACF"}
+{"version":3,"file":"firms.js","sourceRoot":"","sources":["../../src/resources/firms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAc/D;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,aAAc,SAAQ,YAAY;IAC7C;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAoB,KAAK,EAAE,QAAQ,CAAC,CAAC;QACnE,OAAO,GAAG,CAAC,KAAK,CAAC;IACnB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CACP,EAAU,EACV,MAA4B;QAE5B,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,UAAU,kBAAkB,CAAC,EAAE,CAAC,aAAa,UAAU,CAAC;YACtD,MAAM,EAAE,MAAM,EAAE,MAAM;YACtB,KAAK,EAAE,MAAM,EAAE,KAAK;YACpB,SAAS,EAAE,MAAM,EAAE,SAAS;SAC7B,CAAC,EAAE,CACL,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CACd,EAAU,EACV,QAAgD;QAEhD,OAAO,IAAI,CAAC,OAAO,CACjB,MAAM,EACN,UAAU,kBAAkB,CAAC,EAAE,CAAC,qBAAqB,EACrD,QAAQ,CACT,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,IAAuB;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CACT,IAA6B;QAE7B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,qBAAqB,EAAE,IAAI,CAAC,CAAC;IAC3D,CAAC;CACF"}

package/dist/resources/peppol.d.ts

@@ -1,14 +1,81 @@
 import { BaseResource } from "../utils/request.js";
 import type { ClientConfig } from "../utils/request.js";
 import type { PeppolParticipant, DirectorySearchParams, DirectorySearchResult, CompanyLookup } from "../types.js";
+/**
+ * Sub-resource for searching the Peppol Business Card directory.
+ * The directory contains publicly registered Peppol participants.
+ */
 export declare class PeppolDirectoryResource extends BaseResource {
+    /**
+     * Search the Peppol Business Card directory for registered participants.
+     * Supports free-text search and country filtering with pagination.
+     *
+     * @param params - Optional search query, country filter, and pagination
+     * @returns Paginated search results from the directory
+     *
+     * @example
+     * ```typescript
+     * // Search for Slovak companies
+     * const { results, total } = await client.peppol.directory.search({
+     *   q: 'consulting',
+     *   country: 'SK',
+     *   page_size: 50,
+     * });
+     * ```
+     */
     search(params?: DirectorySearchParams): Promise<DirectorySearchResult>;
 }
+/**
+ * Resource for Peppol network operations — SMP lookups, directory search,
+ * and Slovak company information retrieval.
+ *
+ * @example
+ * ```typescript
+ * // Look up a Peppol participant
+ * const participant = await client.peppol.lookup('0245', '1234567890');
+ * console.log(participant.capabilities);
+ *
+ * // Look up a Slovak company by ICO
+ * const company = await client.peppol.companyLookup('12345678');
+ * ```
+ */
 export declare class PeppolResource extends BaseResource {
-    /** Access Peppol Business Card directory */
+    /** Sub-resource for searching the Peppol Business Card directory */
     directory: PeppolDirectoryResource;
     constructor(config: ClientConfig);
+    /**
+     * Look up a Peppol participant by their identifier scheme and value.
+     * Queries the SMP (Service Metadata Publisher) to retrieve the participant's
+     * name, country, and supported document types.
+     *
+     * @param scheme - Peppol identifier scheme (e.g. `"0245"` for Slovak DIČ)
+     * @param identifier - Identifier value within the scheme (e.g. `"1234567890"`)
+     * @returns Participant details including capabilities (supported document types)
+     *
+     * @example
+     * ```typescript
+     * const participant = await client.peppol.lookup('0245', '1234567890');
+     * if (participant.capabilities.length > 0) {
+     *   console.log('Supports:', participant.capabilities.map(c => c.documentTypeId));
+     * }
+     * ```
+     */
     lookup(scheme: string, identifier: string): Promise<PeppolParticipant>;
+    /**
+     * Look up a Slovak company by its ICO (business registration number).
+     * Queries Slovak business registers (ORSR, FinStat) and checks Peppol
+     * registration status. Returns company name, tax IDs, address, and Peppol ID.
+     *
+     * @param ico - Slovak ICO (8-digit business registration number)
+     * @returns Company information including Peppol registration status
+     *
+     * @example
+     * ```typescript
+     * const company = await client.peppol.companyLookup('12345678');
+     * console.log(company.name); // "ACME s.r.o."
+     * console.log(company.peppolId); // "0245:1234567890" or null
+     * ```
+     */
     companyLookup(ico: string): Promise<CompanyLookup>;
 }
 //# sourceMappingURL=peppol.d.ts.map

package/dist/resources/peppol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"peppol.d.ts","sourceRoot":"","sources":["../../src/resources/peppol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACd,MAAM,aAAa,CAAC;AAErB,qBAAa,uBAAwB,SAAQ,YAAY;IACvD,MAAM,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAQvE;AAED,qBAAa,cAAe,SAAQ,YAAY;IAC9C,4CAA4C;IAC5C,SAAS,EAAE,uBAAuB,CAAC;gBAEvB,MAAM,EAAE,YAAY;IAKhC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAItE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAGnD"}
+{"version":3,"file":"peppol.d.ts","sourceRoot":"","sources":["../../src/resources/peppol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACd,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,YAAY;IACvD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAWvE;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,oEAAoE;IACpE,SAAS,EAAE,uBAAuB,CAAC;gBAEvB,MAAM,EAAE,YAAY;IAKhC;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAOtE;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAGnD"}

package/dist/resources/peppol.js

@@ -1,5 +1,26 @@
 import { BaseResource, buildQuery } from "../utils/request.js";
+/**
+ * Sub-resource for searching the Peppol Business Card directory.
+ * The directory contains publicly registered Peppol participants.
+ */
 export class PeppolDirectoryResource extends BaseResource {
+    /**
+     * Search the Peppol Business Card directory for registered participants.
+     * Supports free-text search and country filtering with pagination.
+     *
+     * @param params - Optional search query, country filter, and pagination
+     * @returns Paginated search results from the directory
+     *
+     * @example
+     * ```typescript
+     * // Search for Slovak companies
+     * const { results, total } = await client.peppol.directory.search({
+     *   q: 'consulting',
+     *   country: 'SK',
+     *   page_size: 50,
+     * });
+     * ```
+     */
     search(params) {
         return this.request("GET", `/peppol/directory/search${buildQuery({
             q: params?.q,
@@ -9,16 +30,62 @@ export class PeppolDirectoryResource extends BaseResource {
         })}`);
     }
 }
+/**
+ * Resource for Peppol network operations — SMP lookups, directory search,
+ * and Slovak company information retrieval.
+ *
+ * @example
+ * ```typescript
+ * // Look up a Peppol participant
+ * const participant = await client.peppol.lookup('0245', '1234567890');
+ * console.log(participant.capabilities);
+ *
+ * // Look up a Slovak company by ICO
+ * const company = await client.peppol.companyLookup('12345678');
+ * ```
+ */
 export class PeppolResource extends BaseResource {
-    /** Access Peppol Business Card directory */
+    /** Sub-resource for searching the Peppol Business Card directory */
     directory;
     constructor(config) {
         super(config);
         this.directory = new PeppolDirectoryResource(config);
     }
+    /**
+     * Look up a Peppol participant by their identifier scheme and value.
+     * Queries the SMP (Service Metadata Publisher) to retrieve the participant's
+     * name, country, and supported document types.
+     *
+     * @param scheme - Peppol identifier scheme (e.g. `"0245"` for Slovak DIČ)
+     * @param identifier - Identifier value within the scheme (e.g. `"1234567890"`)
+     * @returns Participant details including capabilities (supported document types)
+     *
+     * @example
+     * ```typescript
+     * const participant = await client.peppol.lookup('0245', '1234567890');
+     * if (participant.capabilities.length > 0) {
+     *   console.log('Supports:', participant.capabilities.map(c => c.documentTypeId));
+     * }
+     * ```
+     */
     lookup(scheme, identifier) {
         return this.request("GET", `/peppol/participants/${encodeURIComponent(scheme)}/${encodeURIComponent(identifier)}`);
     }
+    /**
+     * Look up a Slovak company by its ICO (business registration number).
+     * Queries Slovak business registers (ORSR, FinStat) and checks Peppol
+     * registration status. Returns company name, tax IDs, address, and Peppol ID.
+     *
+     * @param ico - Slovak ICO (8-digit business registration number)
+     * @returns Company information including Peppol registration status
+     *
+     * @example
+     * ```typescript
+     * const company = await client.peppol.companyLookup('12345678');
+     * console.log(company.name); // "ACME s.r.o."
+     * console.log(company.peppolId); // "0245:1234567890" or null
+     * ```
+     */
     companyLookup(ico) {
         return this.request("GET", `/company/lookup/${encodeURIComponent(ico)}`);
     }

package/dist/resources/peppol.js.map

@@ -1 +1 @@
-{"version":3,"file":"peppol.js","sourceRoot":"","sources":["../../src/resources/peppol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAS/D,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACvD,MAAM,CAAC,MAA8B;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,2BAA2B,UAAU,CAAC;YAC/D,CAAC,EAAE,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,MAAM,EAAE,OAAO;YACxB,IAAI,EAAE,MAAM,EAAE,IAAI;YAClB,SAAS,EAAE,MAAM,EAAE,SAAS;SAC7B,CAAC,EAAE,CAAC,CAAC;IACR,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,YAAY;IAC9C,4CAA4C;IAC5C,SAAS,CAA0B;IAEnC,YAAY,MAAoB;QAC9B,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,SAAS,GAAG,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,CAAC,MAAc,EAAE,UAAkB;QACvC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,wBAAwB,kBAAkB,CAAC,MAAM,CAAC,IAAI,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACrH,CAAC;IAED,aAAa,CAAC,GAAW;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,mBAAmB,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;CACF"}
+{"version":3,"file":"peppol.js","sourceRoot":"","sources":["../../src/resources/peppol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAS/D;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACvD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,MAA8B;QACnC,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,2BAA2B,UAAU,CAAC;YACpC,CAAC,EAAE,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,MAAM,EAAE,OAAO;YACxB,IAAI,EAAE,MAAM,EAAE,IAAI;YAClB,SAAS,EAAE,MAAM,EAAE,SAAS;SAC7B,CAAC,EAAE,CACL,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAe,SAAQ,YAAY;IAC9C,oEAAoE;IACpE,SAAS,CAA0B;IAEnC,YAAY,MAAoB;QAC9B,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,SAAS,GAAG,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,MAAc,EAAE,UAAkB;QACvC,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,wBAAwB,kBAAkB,CAAC,MAAM,CAAC,IAAI,kBAAkB,CAAC,UAAU,CAAC,EAAE,CACvF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,GAAW;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,mBAAmB,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;CACF"}

package/dist/resources/reporting.d.ts

@@ -1,6 +1,34 @@
 import { BaseResource } from "../utils/request.js";
 import type { StatisticsParams, Statistics } from "../types.js";
+/**
+ * Resource for retrieving document statistics and reports.
+ *
+ * @example
+ * ```typescript
+ * const stats = await client.reporting.statistics({ from: '2026-01-01', to: '2026-03-31' });
+ * console.log(`Sent: ${stats.outbound.total}, Received: ${stats.inbound.total}`);
+ * ```
+ */
 export declare class ReportingResource extends BaseResource {
+    /**
+     * Get aggregated document statistics for a time period.
+     * Returns counts of sent/received documents, delivery success rates,
+     * and acknowledgment status.
+     *
+     * @param params - Optional date range (defaults to last 30 days)
+     * @returns Aggregated statistics for outbound and inbound documents
+     *
+     * @example
+     * ```typescript
+     * // Get stats for Q1 2026
+     * const stats = await client.reporting.statistics({
+     *   from: '2026-01-01',
+     *   to: '2026-03-31',
+     * });
+     * console.log(`Delivery rate: ${stats.outbound.delivered}/${stats.outbound.total}`);
+     * console.log(`Pending inbox: ${stats.inbound.pending}`);
+     * ```
+     */
     statistics(params?: StatisticsParams): Promise<Statistics>;
 }
 //# sourceMappingURL=reporting.d.ts.map

package/dist/resources/reporting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reporting.d.ts","sourceRoot":"","sources":["../../src/resources/reporting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhE,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,UAAU,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAM3D"}
+{"version":3,"file":"reporting.d.ts","sourceRoot":"","sources":["../../src/resources/reporting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;IACjD;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;CAS3D"}

package/dist/resources/reporting.js

@@ -1,5 +1,33 @@
 import { BaseResource, buildQuery } from "../utils/request.js";
+/**
+ * Resource for retrieving document statistics and reports.
+ *
+ * @example
+ * ```typescript
+ * const stats = await client.reporting.statistics({ from: '2026-01-01', to: '2026-03-31' });
+ * console.log(`Sent: ${stats.outbound.total}, Received: ${stats.inbound.total}`);
+ * ```
+ */
 export class ReportingResource extends BaseResource {
+    /**
+     * Get aggregated document statistics for a time period.
+     * Returns counts of sent/received documents, delivery success rates,
+     * and acknowledgment status.
+     *
+     * @param params - Optional date range (defaults to last 30 days)
+     * @returns Aggregated statistics for outbound and inbound documents
+     *
+     * @example
+     * ```typescript
+     * // Get stats for Q1 2026
+     * const stats = await client.reporting.statistics({
+     *   from: '2026-01-01',
+     *   to: '2026-03-31',
+     * });
+     * console.log(`Delivery rate: ${stats.outbound.delivered}/${stats.outbound.total}`);
+     * console.log(`Pending inbox: ${stats.inbound.pending}`);
+     * ```
+     */
     statistics(params) {
         return this.request("GET", `/reporting/statistics${buildQuery({
             from: params?.from,

package/dist/resources/reporting.js.map

@@ -1 +1 @@
-{"version":3,"file":"reporting.js","sourceRoot":"","sources":["../../src/resources/reporting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAG/D,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACjD,UAAU,CAAC,MAAyB;QAClC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,wBAAwB,UAAU,CAAC;YAC5D,IAAI,EAAE,MAAM,EAAE,IAAI;YAClB,EAAE,EAAE,MAAM,EAAE,EAAE;SACf,CAAC,EAAE,CAAC,CAAC;IACR,CAAC;CACF"}
+{"version":3,"file":"reporting.js","sourceRoot":"","sources":["../../src/resources/reporting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAG/D;;;;;;;;GAQG;AACH,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACjD;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,MAAyB;QAClC,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,wBAAwB,UAAU,CAAC;YACjC,IAAI,EAAE,MAAM,EAAE,IAAI;YAClB,EAAE,EAAE,MAAM,EAAE,EAAE;SACf,CAAC,EAAE,CACL,CAAC;IACJ,CAAC;CACF"}

package/dist/resources/webhooks.d.ts

@@ -1,25 +1,230 @@
 import { BaseResource } from "../utils/request.js";
 import type { ClientConfig } from "../utils/request.js";
-import type { CreateWebhookRequest, UpdateWebhookRequest, Webhook, WebhookDetail, WebhookWithDeliveries, WebhookQueueParams, WebhookQueueResponse, WebhookQueueAllParams, WebhookQueueAllResponse } from "../types.js";
+import type { CreateWebhookRequest, UpdateWebhookRequest, Webhook, WebhookDetail, WebhookWithDeliveries, WebhookQueueParams, WebhookQueueResponse, WebhookQueueAllParams, WebhookQueueAllResponse, WebhookTestResponse, WebhookDeliveriesParams, WebhookDeliveriesResponse, WebhookEvent } from "../types.js";
+/**
+ * Sub-resource for the webhook pull queue — an alternative to push webhooks.
+ * Use the pull queue when your server cannot receive inbound HTTPS requests.
+ * Events accumulate in the queue and must be acknowledged after processing.
+ *
+ * @example
+ * ```typescript
+ * // Poll-based event consumption loop
+ * const { items, has_more } = await client.webhooks.queue.pull({ limit: 50 });
+ * for (const item of items) {
+ *   await processEvent(item);
+ *   await client.webhooks.queue.ack(item.id);
+ * }
+ * ```
+ */
 export declare class WebhookQueueResource extends BaseResource {
+    /**
+     * Pull unacknowledged events from the webhook queue.
+     * Events remain in the queue until explicitly acknowledged via `ack()` or `batchAck()`.
+     *
+     * @param params - Optional limit and event type filter
+     * @returns Array of queue items and whether more items are available
+     *
+     * @example
+     * ```typescript
+     * const { items, has_more } = await client.webhooks.queue.pull({
+     *   limit: 20,
+     *   event_type: 'document.received',
+     * });
+     * ```
+     */
     pull(params?: WebhookQueueParams): Promise<WebhookQueueResponse>;
+    /**
+     * Acknowledge (remove) a single event from the queue after processing.
+     *
+     * @param eventId - The event ID to acknowledge
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * await client.webhooks.queue.ack('event-uuid');
+     * ```
+     */
     ack(eventId: string): Promise<void>;
+    /**
+     * Acknowledge (remove) multiple events from the queue in a single request.
+     *
+     * @param eventIds - Array of event IDs to acknowledge
+     * @returns void
+     *
+     * @example
+     * ```typescript
+     * const { items } = await client.webhooks.queue.pull({ limit: 50 });
+     * // Process all items...
+     * await client.webhooks.queue.batchAck(items.map(i => i.id));
+     * ```
+     */
     batchAck(eventIds: string[]): Promise<void>;
+    /**
+     * Pull events across all managed firms (integrator endpoint).
+     * Only available with integrator API keys (`sk_int_*`).
+     * Use the `since` parameter for cursor-based polling.
+     *
+     * @param params - Optional limit and since timestamp for cursor-based polling
+     * @returns Array of events across all firms with count
+     *
+     * @example
+     * ```typescript
+     * const { events, count } = await client.webhooks.queue.pullAll({
+     *   since: '2026-04-11T00:00:00Z',
+     *   limit: 200,
+     * });
+     * ```
+     */
     pullAll(params?: WebhookQueueAllParams): Promise<WebhookQueueAllResponse>;
+    /**
+     * Acknowledge (remove) multiple events from the cross-firm queue (integrator endpoint).
+     * Only available with integrator API keys (`sk_int_*`).
+     *
+     * @param eventIds - Array of event IDs to acknowledge
+     * @returns Object with the count of acknowledged events
+     *
+     * @example
+     * ```typescript
+     * const { events } = await client.webhooks.queue.pullAll({ limit: 100 });
+     * // Process all events...
+     * const { acknowledged } = await client.webhooks.queue.batchAckAll(
+     *   events.map(e => e.event_id),
+     * );
+     * ```
+     */
     batchAckAll(eventIds: string[]): Promise<{
         acknowledged: number;
     }>;
 }
+/**
+ * Resource for managing webhook subscriptions and the pull queue.
+ * Webhooks notify your server about document events (sent, received, validated).
+ * Choose between push webhooks (server receives HTTPS POST) or the pull queue
+ * (your code polls for events).
+ *
+ * @example
+ * ```typescript
+ * // Create a push webhook
+ * const webhook = await client.webhooks.create({
+ *   url: 'https://example.com/webhooks/epostak',
+ *   events: ['document.received', 'document.sent'],
+ * });
+ * // Store webhook.secret for HMAC verification
+ * ```
+ */
 export declare class WebhooksResource extends BaseResource {
-    /** Access the webhook pull queue for polling-based consumption */
+    /** Sub-resource for the pull queue (polling-based event consumption) */
     queue: WebhookQueueResource;
     constructor(config: ClientConfig);
+    /**
+     * Create a new webhook subscription. Returns the HMAC-SHA256 signing secret
+     * which is only available at creation time — store it securely.
+     *
+     * @param body - Webhook URL and optional event filter
+     * @returns Webhook details including the one-time signing secret
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.create({
+     *   url: 'https://example.com/webhooks',
+     *   events: ['document.received'],
+     * });
+     * console.log(webhook.secret); // Store this securely!
+     * ```
+     */
     create(body: CreateWebhookRequest): Promise<WebhookDetail>;
+    /**
+     * List all webhook subscriptions for the current account.
+     *
+     * @returns Array of webhook subscriptions
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await client.webhooks.list();
+     * webhooks.forEach(w => console.log(w.url, w.isActive));
+     * ```
+     */
     list(): Promise<Webhook[]>;
+    /**
+     * Get a webhook subscription by ID, including recent delivery history.
+     * Use the delivery history to debug failed webhook deliveries.
+     *
+     * @param id - Webhook UUID
+     * @returns Webhook details with delivery history
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.get('webhook-uuid');
+     * const failedDeliveries = webhook.deliveries.filter(d => d.status === 'failed');
+     * ```
+     */
     get(id: string): Promise<WebhookWithDeliveries>;
+    /**
+     * Update a webhook subscription. Use this to change the URL, event filter,
+     * or pause/resume the webhook.
+     *
+     * @param id - Webhook UUID
+     * @param body - Fields to update (omit to leave unchanged)
+     * @returns The updated webhook
+     *
+     * @example
+     * ```typescript
+     * // Pause a webhook
+     * await client.webhooks.update('webhook-uuid', { isActive: false });
+     *
+     * // Change URL and events
+     * await client.webhooks.update('webhook-uuid', {
+     *   url: 'https://new-url.com/webhooks',
+     *   events: ['document.received', 'document.validated'],
+     * });
+     * ```
+     */
     update(id: string, body: UpdateWebhookRequest): Promise<Webhook>;
+    /**
+     * Delete a webhook subscription. Stops all future deliveries for this webhook.
+     *
+     * @param id - Webhook UUID to delete
+     * @returns Confirmation with `deleted: true`
+     *
+     * @example
+     * ```typescript
+     * await client.webhooks.delete('webhook-uuid');
+     * ```
+     */
     delete(id: string): Promise<{
         deleted: boolean;
     }>;
+    /**
+     * Send a test event to a webhook endpoint. Useful for verifying your
+     * webhook URL is reachable and responding correctly.
+     *
+     * @param id - Webhook UUID to test
+     * @param event - Event type to simulate (defaults to server-chosen event)
+     * @returns Test result with success status, HTTP status code, and response time
+     *
+     * @example
+     * ```typescript
+     * const result = await client.webhooks.test('webhook-uuid');
+     * console.log(result.success, result.responseTime + 'ms');
+     * ```
+     */
+    test(id: string, event?: WebhookEvent): Promise<WebhookTestResponse>;
+    /**
+     * Get paginated delivery history for a webhook. Use this to inspect
+     * individual delivery attempts, filter by status, and debug failures.
+     *
+     * @param id - Webhook UUID
+     * @param params - Optional pagination and filter parameters
+     * @returns Paginated list of delivery records with total count
+     *
+     * @example
+     * ```typescript
+     * const { deliveries, total } = await client.webhooks.deliveries('webhook-uuid', {
+     *   status: 'FAILED',
+     *   limit: 50,
+     * });
+     * ```
+     */
+    deliveries(id: string, params?: WebhookDeliveriesParams): Promise<WebhookDeliveriesResponse>;
 }
 //# sourceMappingURL=webhooks.d.ts.map

package/dist/resources/webhooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/resources/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,OAAO,EACP,aAAa,EACb,qBAAqB,EAErB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAErB,qBAAa,oBAAqB,SAAQ,YAAY;IACpD,IAAI,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAOhE,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,OAAO,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAOzE,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CAGnE;AAED,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,kEAAkE;IAClE,KAAK,EAAE,oBAAoB,CAAC;gBAEhB,MAAM,EAAE,YAAY;IAKhC,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IAIpD,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAKhC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI/C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAIhE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAGlD"}
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/resources/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,OAAO,EACP,aAAa,EACb,qBAAqB,EAErB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,yBAAyB,EACzB,YAAY,EACb,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IACpD;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAUhE;;;;;;;;;;OAUG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3C;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAUzE;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CAKnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,wEAAwE;IACxE,KAAK,EAAE,oBAAoB,CAAC;gBAEhB,MAAM,EAAE,YAAY;IAKhC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IAI1D;;;;;;;;;;OAUG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAKhC;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI/C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAIhE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAIjD;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAUpE;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CACR,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,yBAAyB,CAAC;CAWtC"}