@neo-edi/sdk 1.0.19 → 1.0.21

package/README.md

@@ -267,6 +267,94 @@ const data = await client.graphql.query<{ edi852Headers: Edi852Header[] }>(`
 `, { filter: { vendorPartnerId: 'VENDOR-001' } });
 ```
 
+## Webhooks
+
+Register endpoints that receive HMAC-signed HTTP callbacks when events happen for a
+trading partner — e.g. `document.ingested` when a delivery is ingested — so you don't
+have to poll.
+
+```typescript
+// Create (subscribe) an endpoint.
+// The returned signingSecret is shown ONCE — store it now.
+const endpoint = await client.webhooks.create({
+  partnerId: 'PARTNER-001',
+  url: 'https://your-app.com/hooks/neo-edi',
+  description: 'Production receiver',
+  eventTypes: ['document.ingested']   // omit to subscribe to all events
+});
+console.log(endpoint.signingSecret);  // whsec_... — persist this securely
+
+// List endpoints for a partner
+const endpoints = await client.webhooks.list('PARTNER-001');
+
+// Get one endpoint
+const one = await client.webhooks.get(endpoint.id);
+
+// Update — change the URL, events, or pause delivery with isActive: false
+await client.webhooks.update(endpoint.id, {
+  url: 'https://your-app.com/hooks/neo-edi/v2',
+  isActive: false
+});
+
+// Delete (unsubscribe)
+await client.webhooks.delete(endpoint.id);
+
+// Inspect recent delivery attempts (audit / debugging)
+const deliveries = await client.webhooks.listDeliveries(endpoint.id, { limit: 20 });
+for (const d of deliveries) {
+  console.log(d.status, d.responseStatus, d.attemptCount);
+}
+```
+
+### Receiving & verifying deliveries
+
+Each delivery is an HTTP `POST` to your URL with a JSON envelope
+(`{ id, type, partnerId, createdAt, data }`) and these headers:
+
+| Header | Example | Purpose |
+|--------|---------|---------|
+| `X-Webhook-Timestamp` | `1717416000` | Unix seconds; part of the signed content |
+| `X-Webhook-Signature` | `t=1717416000,v1=9f86d08...` | `v1` is the HMAC-SHA256 hex digest |
+
+Verify by recomputing `HMAC_SHA256(signingSecret, "{timestamp}.{rawBody}")` over the
+**raw** body (before JSON parsing) and comparing it to the `v1=` value. Example with
+Express:
+
+```typescript
+import crypto from 'node:crypto';
+import express from 'express';
+
+const app = express();
+
+// Capture the raw body — the signature is computed over the exact bytes sent.
+app.post(
+  '/hooks/neo-edi',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const sig = req.header('X-Webhook-Signature') ?? '';
+    const parts = Object.fromEntries(sig.split(',').map((kv) => kv.split('=')));
+    const rawBody = req.body.toString('utf8');
+
+    const expected = crypto
+      .createHmac('sha256', process.env.WEBHOOK_SECRET!)
+      .update(`${parts.t}.${rawBody}`)
+      .digest('hex');
+
+    const valid =
+      parts.v1?.length === expected.length &&
+      crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
+
+    if (!valid) return res.status(401).send('bad signature');
+
+    const event = JSON.parse(rawBody);
+    // Dedupe on event.id — it is stable across retries.
+    // ... handle event.data ...
+
+    res.sendStatus(200); // any 2xx acknowledges; otherwise it's retried (up to 3x)
+  }
+);
+```
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { ListCustomersParams, EdiCustomer, CustomerIdentifierType, CreateCustomerRequest, UpdateCustomerRequest, ListSubCustomersParams, SubCustomerWithIdentifiers, SubCustomer, AddSubCustomerResponse, CreateSubCustomerRequest, CreateSubCustomerResponse, EdiPartner, RegisterPartnerCustomerRequest, PartnerCustomerRegistrationResult, GetSubscriptionsParams, CustomerSubscriptionsResponse, IdentifierPattern, ListMappingTemplatesParams, EdiMappingTemplate, CreateMappingTemplateRequest, UpdateMappingTemplateRequest, CsvHeaderMappingCollection, CsvDataTransformationConfig, IngestCsvResult, DryRunResult } from '@neo-edi/types';
-export { AddSubCustomerRequest, AddSubCustomerResponse, Address, ApiResponse, CreateCustomerRequest, CreateMappingTemplateRequest, CreatePartnerRequest, CsvDataTransformationConfig, CsvHeaderMappingCollection, CsvHeaderMappingConfig, CsvHeaderTableEntry, DryRunResult, Edi852DeliverySummary, Edi852Header, Edi852HeaderFilter, Edi852Item, Edi852Location, Edi852Status, EdiCustomer, EdiMappingTemplate, EdiPartner, EdiPartnerCustomer, IngestCsvResult, ListCustomersParams, ListMappingTemplatesParams, ListSubCustomersParams, PaginatedResponse, PartnerCustomerRegistrationResult, RegisterPartnerCustomerRequest, SubCustomer, SubCustomersResponse, UpdateCustomerRequest, UpdateMappingTemplateRequest, UpdatePartnerRequest } from '@neo-edi/types';
+import { ListCustomersParams, EdiCustomer, CustomerIdentifierType, CreateCustomerRequest, UpdateCustomerRequest, ListSubCustomersParams, SubCustomerWithIdentifiers, SubCustomer, AddSubCustomerResponse, CreateSubCustomerRequest, CreateSubCustomerResponse, EdiPartner, RegisterPartnerCustomerRequest, PartnerCustomerRegistrationResult, GetSubscriptionsParams, CustomerSubscriptionsResponse, IdentifierPattern, ListMappingTemplatesParams, EdiMappingTemplate, CreateMappingTemplateRequest, UpdateMappingTemplateRequest, CsvHeaderMappingCollection, CsvDataTransformationConfig, IngestCsvResult, DryRunResult, WebhookEndpoint, CreateWebhookRequest, WebhookEndpointWithSecret, UpdateWebhookRequest, ListWebhookDeliveriesParams, WebhookDelivery } from '@neo-edi/types';
+export { AddSubCustomerRequest, AddSubCustomerResponse, Address, ApiResponse, CreateCustomerRequest, CreateMappingTemplateRequest, CreatePartnerRequest, CreateWebhookRequest, CsvDataTransformationConfig, CsvHeaderMappingCollection, CsvHeaderMappingConfig, CsvHeaderTableEntry, DryRunResult, Edi852DeliverySummary, Edi852Header, Edi852HeaderFilter, Edi852Item, Edi852Location, Edi852Status, EdiCustomer, EdiMappingTemplate, EdiPartner, EdiPartnerCustomer, IngestCsvResult, ListCustomersParams, ListMappingTemplatesParams, ListSubCustomersParams, ListWebhookDeliveriesParams, PaginatedResponse, PartnerCustomerRegistrationResult, RegisterPartnerCustomerRequest, SubCustomer, SubCustomersResponse, UpdateCustomerRequest, UpdateMappingTemplateRequest, UpdatePartnerRequest, UpdateWebhookRequest, WebhookDelivery, WebhookDeliveryStatus, WebhookEndpoint, WebhookEndpointWithSecret, WebhookEventType } from '@neo-edi/types';
 
 /**
  * Base HTTP client for the SDK
@@ -440,6 +440,49 @@ declare const Queries: {
     GET_EXECUTION_SUMMARIES: string;
 };
 
+/**
+ * Webhooks resource
+ *
+ * Register endpoints that receive HMAC-signed HTTP callbacks when events occur
+ * for a trading partner — e.g. `document.ingested` when a delivery is ingested.
+ *
+ * Verifying incoming webhooks (on your receiver):
+ *   const expected = "sha256=" + hmacSHA256(`${timestamp}.${rawBody}`, signingSecret)
+ * compare against the `v1=` value in the `X-Webhook-Signature` header, where
+ * `timestamp` is the `X-Webhook-Timestamp` header (and the `t=` value).
+ */
+
+declare class WebhooksResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List webhook endpoints for a trading partner.
+     */
+    list(partnerId: string): Promise<WebhookEndpoint[]>;
+    /**
+     * Get a single webhook endpoint by id.
+     */
+    get(endpointId: string): Promise<WebhookEndpoint>;
+    /**
+     * Create (subscribe) a webhook endpoint. The returned object includes the
+     * `signingSecret` — store it now, it is never returned again.
+     */
+    create(data: CreateWebhookRequest): Promise<WebhookEndpointWithSecret>;
+    /**
+     * Update a webhook endpoint (url, description, subscribed events, or enable/
+     * disable via `isActive`).
+     */
+    update(endpointId: string, data: UpdateWebhookRequest): Promise<WebhookEndpoint>;
+    /**
+     * Delete (unsubscribe) a webhook endpoint.
+     */
+    delete(endpointId: string): Promise<void>;
+    /**
+     * List recent delivery attempts for an endpoint (audit / debugging).
+     */
+    listDeliveries(endpointId: string, params?: ListWebhookDeliveriesParams): Promise<WebhookDelivery[]>;
+}
+
 /**
  * Neo-EDI SDK Client
  */
@@ -529,6 +572,10 @@ declare class NeoEdiClient {
      * GraphQL query operations
      */
     readonly graphql: GraphQLResource;
+    /**
+     * Webhook subscription operations
+     */
+    readonly webhooks: WebhooksResource;
     constructor(config: NeoEdiClientConfig);
 }
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ListCustomersParams, EdiCustomer, CustomerIdentifierType, CreateCustomerRequest, UpdateCustomerRequest, ListSubCustomersParams, SubCustomerWithIdentifiers, SubCustomer, AddSubCustomerResponse, CreateSubCustomerRequest, CreateSubCustomerResponse, EdiPartner, RegisterPartnerCustomerRequest, PartnerCustomerRegistrationResult, GetSubscriptionsParams, CustomerSubscriptionsResponse, IdentifierPattern, ListMappingTemplatesParams, EdiMappingTemplate, CreateMappingTemplateRequest, UpdateMappingTemplateRequest, CsvHeaderMappingCollection, CsvDataTransformationConfig, IngestCsvResult, DryRunResult } from '@neo-edi/types';
-export { AddSubCustomerRequest, AddSubCustomerResponse, Address, ApiResponse, CreateCustomerRequest, CreateMappingTemplateRequest, CreatePartnerRequest, CsvDataTransformationConfig, CsvHeaderMappingCollection, CsvHeaderMappingConfig, CsvHeaderTableEntry, DryRunResult, Edi852DeliverySummary, Edi852Header, Edi852HeaderFilter, Edi852Item, Edi852Location, Edi852Status, EdiCustomer, EdiMappingTemplate, EdiPartner, EdiPartnerCustomer, IngestCsvResult, ListCustomersParams, ListMappingTemplatesParams, ListSubCustomersParams, PaginatedResponse, PartnerCustomerRegistrationResult, RegisterPartnerCustomerRequest, SubCustomer, SubCustomersResponse, UpdateCustomerRequest, UpdateMappingTemplateRequest, UpdatePartnerRequest } from '@neo-edi/types';
+import { ListCustomersParams, EdiCustomer, CustomerIdentifierType, CreateCustomerRequest, UpdateCustomerRequest, ListSubCustomersParams, SubCustomerWithIdentifiers, SubCustomer, AddSubCustomerResponse, CreateSubCustomerRequest, CreateSubCustomerResponse, EdiPartner, RegisterPartnerCustomerRequest, PartnerCustomerRegistrationResult, GetSubscriptionsParams, CustomerSubscriptionsResponse, IdentifierPattern, ListMappingTemplatesParams, EdiMappingTemplate, CreateMappingTemplateRequest, UpdateMappingTemplateRequest, CsvHeaderMappingCollection, CsvDataTransformationConfig, IngestCsvResult, DryRunResult, WebhookEndpoint, CreateWebhookRequest, WebhookEndpointWithSecret, UpdateWebhookRequest, ListWebhookDeliveriesParams, WebhookDelivery } from '@neo-edi/types';
+export { AddSubCustomerRequest, AddSubCustomerResponse, Address, ApiResponse, CreateCustomerRequest, CreateMappingTemplateRequest, CreatePartnerRequest, CreateWebhookRequest, CsvDataTransformationConfig, CsvHeaderMappingCollection, CsvHeaderMappingConfig, CsvHeaderTableEntry, DryRunResult, Edi852DeliverySummary, Edi852Header, Edi852HeaderFilter, Edi852Item, Edi852Location, Edi852Status, EdiCustomer, EdiMappingTemplate, EdiPartner, EdiPartnerCustomer, IngestCsvResult, ListCustomersParams, ListMappingTemplatesParams, ListSubCustomersParams, ListWebhookDeliveriesParams, PaginatedResponse, PartnerCustomerRegistrationResult, RegisterPartnerCustomerRequest, SubCustomer, SubCustomersResponse, UpdateCustomerRequest, UpdateMappingTemplateRequest, UpdatePartnerRequest, UpdateWebhookRequest, WebhookDelivery, WebhookDeliveryStatus, WebhookEndpoint, WebhookEndpointWithSecret, WebhookEventType } from '@neo-edi/types';
 
 /**
  * Base HTTP client for the SDK
@@ -440,6 +440,49 @@ declare const Queries: {
     GET_EXECUTION_SUMMARIES: string;
 };
 
+/**
+ * Webhooks resource
+ *
+ * Register endpoints that receive HMAC-signed HTTP callbacks when events occur
+ * for a trading partner — e.g. `document.ingested` when a delivery is ingested.
+ *
+ * Verifying incoming webhooks (on your receiver):
+ *   const expected = "sha256=" + hmacSHA256(`${timestamp}.${rawBody}`, signingSecret)
+ * compare against the `v1=` value in the `X-Webhook-Signature` header, where
+ * `timestamp` is the `X-Webhook-Timestamp` header (and the `t=` value).
+ */
+
+declare class WebhooksResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List webhook endpoints for a trading partner.
+     */
+    list(partnerId: string): Promise<WebhookEndpoint[]>;
+    /**
+     * Get a single webhook endpoint by id.
+     */
+    get(endpointId: string): Promise<WebhookEndpoint>;
+    /**
+     * Create (subscribe) a webhook endpoint. The returned object includes the
+     * `signingSecret` — store it now, it is never returned again.
+     */
+    create(data: CreateWebhookRequest): Promise<WebhookEndpointWithSecret>;
+    /**
+     * Update a webhook endpoint (url, description, subscribed events, or enable/
+     * disable via `isActive`).
+     */
+    update(endpointId: string, data: UpdateWebhookRequest): Promise<WebhookEndpoint>;
+    /**
+     * Delete (unsubscribe) a webhook endpoint.
+     */
+    delete(endpointId: string): Promise<void>;
+    /**
+     * List recent delivery attempts for an endpoint (audit / debugging).
+     */
+    listDeliveries(endpointId: string, params?: ListWebhookDeliveriesParams): Promise<WebhookDelivery[]>;
+}
+
 /**
  * Neo-EDI SDK Client
  */
@@ -529,6 +572,10 @@ declare class NeoEdiClient {
      * GraphQL query operations
      */
     readonly graphql: GraphQLResource;
+    /**
+     * Webhook subscription operations
+     */
+    readonly webhooks: WebhooksResource;
     constructor(config: NeoEdiClientConfig);
 }
 

package/dist/index.js

@@ -63,7 +63,7 @@ var NeoEdiValidationError = class extends NeoEdiError {
 // package.json
 var package_default = {
   name: "@neo-edi/sdk",
-  version: "1.0.19",
+  version: "1.0.21",
   description: "TypeScript SDK for the Neo-EDI platform",
   main: "./dist/index.js",
   module: "./dist/index.mjs",
@@ -786,6 +786,84 @@ var Queries = {
   `
 };
 
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List webhook endpoints for a trading partner.
+   */
+  async list(partnerId) {
+    const response = await this.http.get(
+      "/api/v1/webhooks",
+      { partnerId }
+    );
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+  /**
+   * Get a single webhook endpoint by id.
+   */
+  async get(endpointId) {
+    const response = await this.http.get(
+      `/api/v1/webhooks/${encodeURIComponent(endpointId)}`
+    );
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+  /**
+   * Create (subscribe) a webhook endpoint. The returned object includes the
+   * `signingSecret` — store it now, it is never returned again.
+   */
+  async create(data) {
+    const response = await this.http.post("/api/v1/webhooks", data);
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+  /**
+   * Update a webhook endpoint (url, description, subscribed events, or enable/
+   * disable via `isActive`).
+   */
+  async update(endpointId, data) {
+    const response = await this.http.patch(
+      `/api/v1/webhooks/${encodeURIComponent(endpointId)}`,
+      data
+    );
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+  /**
+   * Delete (unsubscribe) a webhook endpoint.
+   */
+  async delete(endpointId) {
+    await this.http.delete(
+      `/api/v1/webhooks/${encodeURIComponent(endpointId)}`
+    );
+  }
+  /**
+   * List recent delivery attempts for an endpoint (audit / debugging).
+   */
+  async listDeliveries(endpointId, params) {
+    const response = await this.http.get(
+      `/api/v1/webhooks/${encodeURIComponent(endpointId)}/deliveries`,
+      params
+    );
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+};
+
 // src/client.ts
 var NeoEdiClient = class {
   constructor(config) {
@@ -803,6 +881,7 @@ var NeoEdiClient = class {
     this.mappingTemplates = new MappingTemplatesResource(this.http);
     this.ingest = new IngestResource(this.http);
     this.graphql = new GraphQLResource(this.http);
+    this.webhooks = new WebhooksResource(this.http);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -32,7 +32,7 @@ var NeoEdiValidationError = class extends NeoEdiError {
 // package.json
 var package_default = {
   name: "@neo-edi/sdk",
-  version: "1.0.19",
+  version: "1.0.21",
   description: "TypeScript SDK for the Neo-EDI platform",
   main: "./dist/index.js",
   module: "./dist/index.mjs",
@@ -755,6 +755,84 @@ var Queries = {
   `
 };
 
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List webhook endpoints for a trading partner.
+   */
+  async list(partnerId) {
+    const response = await this.http.get(
+      "/api/v1/webhooks",
+      { partnerId }
+    );
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+  /**
+   * Get a single webhook endpoint by id.
+   */
+  async get(endpointId) {
+    const response = await this.http.get(
+      `/api/v1/webhooks/${encodeURIComponent(endpointId)}`
+    );
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+  /**
+   * Create (subscribe) a webhook endpoint. The returned object includes the
+   * `signingSecret` — store it now, it is never returned again.
+   */
+  async create(data) {
+    const response = await this.http.post("/api/v1/webhooks", data);
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+  /**
+   * Update a webhook endpoint (url, description, subscribed events, or enable/
+   * disable via `isActive`).
+   */
+  async update(endpointId, data) {
+    const response = await this.http.patch(
+      `/api/v1/webhooks/${encodeURIComponent(endpointId)}`,
+      data
+    );
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+  /**
+   * Delete (unsubscribe) a webhook endpoint.
+   */
+  async delete(endpointId) {
+    await this.http.delete(
+      `/api/v1/webhooks/${encodeURIComponent(endpointId)}`
+    );
+  }
+  /**
+   * List recent delivery attempts for an endpoint (audit / debugging).
+   */
+  async listDeliveries(endpointId, params) {
+    const response = await this.http.get(
+      `/api/v1/webhooks/${encodeURIComponent(endpointId)}/deliveries`,
+      params
+    );
+    if (!response.success) {
+      throw new Error(response.error);
+    }
+    return response.data;
+  }
+};
+
 // src/client.ts
 var NeoEdiClient = class {
   constructor(config) {
@@ -772,6 +850,7 @@ var NeoEdiClient = class {
     this.mappingTemplates = new MappingTemplatesResource(this.http);
     this.ingest = new IngestResource(this.http);
     this.graphql = new GraphQLResource(this.http);
+    this.webhooks = new WebhooksResource(this.http);
   }
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo-edi/sdk",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "description": "TypeScript SDK for the Neo-EDI platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@neo-edi/types": "1.0.19"
+    "@neo-edi/types": "1.0.21"
   },
   "devDependencies": {
     "@types/node": "^20",
@@ -24,7 +24,7 @@
     "typescript": "^5.0.0"
   },
   "peerDependencies": {
-    "@neo-edi/types": "1.0.19"
+    "@neo-edi/types": "1.0.21"
   },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",