wai-license-connector-sdk 0.1.0

package/README.md

@@ -0,0 +1,399 @@
+# @wai-license/connector-sdk
+
+Official SDK for making any Node.js application a **Wai License-compatible connector**.
+
+Framework-agnostic · Node 20+ · Native fetch only · No axios
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @wai-license/connector-sdk
+
+# pnpm (monorepo)
+pnpm add @wai-license/connector-sdk
+```
+
+Node 20 or later is required. No polyfills needed — the SDK uses the built-in `fetch`, `crypto`, and `fs` APIs.
+
+---
+
+## Quick Start
+
+```ts
+import { WaiConnector } from '@wai-license/connector-sdk';
+
+const connector = new WaiConnector({
+  // Identity
+  connectorCode: 'alcya',          // Stable code — matches the connector registered in Wai License
+  connectorName: 'ALCYA',
+  connectorVersion: '1.0.0',
+  connectorType: 'api',
+
+  // Connection
+  waiUrl: process.env.WAI_URL!,    // e.g. https://wai.example.com
+  apiKey: process.env.WAI_API_KEY!,
+
+  // Capabilities and actions
+  capabilities: ['customers', 'licenses'],
+  actions: [
+    {
+      code: 'activate_license',
+      name: 'Activate License',
+      endpoint: { url: '/wai/licenses/activate' },
+    },
+    {
+      code: 'create_customer',
+      name: 'Create Customer',
+      endpoint: { url: '/wai/customers', method: 'POST' },
+    },
+  ],
+
+  // Optional hooks
+  onRegister: (ctx) => console.log('Registered:', ctx.instanceId),
+  onHeartbeat: (ctx) => console.log('Heartbeat sent, took', ctx.durationMs, 'ms'),
+  onConfiguration: (ctx) => console.log('Config refreshed at', ctx.fetchedAt),
+  onError: (err) => console.error('Connector error:', err.name, err.message),
+});
+
+await connector.start();
+console.log('Connector started, instanceId:', connector.instanceId);
+```
+
+`start()` will:
+1. Load or create a persistent instance identity (`.wai-connector.json`)
+2. Register with Wai License
+3. Send the first heartbeat
+4. Start the heartbeat loop (default: every 60 seconds)
+
+---
+
+## Express Integration
+
+```ts
+import express from 'express';
+import { WaiConnector } from '@wai-license/connector-sdk';
+
+const connector = new WaiConnector({ /* ...options... */ });
+
+const app = express();
+app.use(express.json());
+
+// Serve the manifest — Wai License polls this URL
+app.get('/.well-known/wai-license.json', async (_req, res) => {
+  const handler = connector.handlers.manifest();
+  const response = handler();
+  const body = await response.json();
+  res.json(body);
+});
+
+// Optional: let Wai License push a registration confirmation
+app.post('/wai/register', async (req, res) => {
+  const handler = connector.handlers.register();
+  const response = handler(req as unknown as Request);
+  const body = await response.json();
+  res.status(response.status).json(body);
+});
+
+// Optional: heartbeat ping endpoint
+app.post('/wai/heartbeat', async (_req, res) => {
+  const handler = connector.handlers.heartbeat();
+  const response = handler();
+  const body = await response.json();
+  res.status(response.status).json(body);
+});
+
+// Start everything
+app.listen(3000, async () => {
+  await connector.start();
+  console.log('Express + Wai Connector running on :3000');
+});
+```
+
+---
+
+## Fastify Integration
+
+```ts
+import Fastify from 'fastify';
+import { WaiConnector } from '@wai-license/connector-sdk';
+
+const connector = new WaiConnector({ /* ...options... */ });
+const app = Fastify();
+
+app.get('/.well-known/wai-license.json', async (_request, reply) => {
+  const handler = connector.handlers.manifest();
+  const response = handler();
+  const body = await response.json();
+  return reply.type('application/json').send(body);
+});
+
+app.post('/wai/heartbeat', async (_request, reply) => {
+  const handler = connector.handlers.heartbeat();
+  const response = handler();
+  const body = await response.json();
+  return reply.status(response.status).send(body);
+});
+
+const start = async () => {
+  await connector.start();
+  await app.listen({ port: 3000 });
+  console.log('Fastify + Wai Connector running on :3000');
+};
+
+start().catch(console.error);
+```
+
+---
+
+## ALCYA Integration Example
+
+ALCYA is a Node.js SaaS application that manages software licenses. Here is a complete integration using the connector SDK with Express:
+
+```ts
+// src/wai-connector.ts
+import { WaiConnector, AuthenticationError, NetworkError } from '@wai-license/connector-sdk';
+import { logger } from './logger';
+
+export const connector = new WaiConnector({
+  connectorCode: 'alcya',
+  connectorName: 'ALCYA',
+  connectorVersion: process.env.npm_package_version ?? '1.0.0',
+  connectorType: 'api',
+  waiUrl: process.env.WAI_URL!,
+  apiKey: process.env.WAI_API_KEY!,
+  capabilities: ['customers', 'licenses', 'subscriptions'],
+  actions: [
+    { code: 'activate_license',   name: 'Activate License',   endpoint: { url: '/wai/licenses/activate' } },
+    { code: 'deactivate_license', name: 'Deactivate License', endpoint: { url: '/wai/licenses/deactivate' } },
+    { code: 'create_customer',    name: 'Create Customer',    endpoint: { url: '/wai/customers' } },
+    { code: 'suspend_customer',   name: 'Suspend Customer',   endpoint: { url: '/wai/customers/suspend' } },
+  ],
+  heartbeatIntervalMs: 30_000,
+  onRegister: (ctx) => logger.info({ instanceId: ctx.instanceId }, 'Registered with Wai License'),
+  onHeartbeat: (ctx) => logger.debug({ durationMs: ctx.durationMs }, 'Heartbeat sent'),
+  onConfiguration: (ctx) => {
+    logger.info('Wai configuration refreshed');
+    // React to configuration changes
+    const config = ctx.config;
+    if (config['featureFlags']) {
+      applyFeatureFlags(config['featureFlags'] as Record<string, boolean>);
+    }
+  },
+  onError: (err) => {
+    if (err instanceof AuthenticationError) {
+      logger.error('Invalid WAI_API_KEY — check environment configuration');
+    } else if (err instanceof NetworkError) {
+      logger.warn({ message: err.message }, 'Wai License unreachable, will retry');
+    } else {
+      logger.error({ err }, 'Wai Connector error');
+    }
+  },
+});
+
+function applyFeatureFlags(_flags: Record<string, boolean>): void {
+  // application-specific flag application
+}
+```
+
+```ts
+// src/app.ts
+import express from 'express';
+import { connector } from './wai-connector';
+
+const app = express();
+app.use(express.json());
+
+// Manifest endpoint — Wai License discovers the connector from here
+app.get('/.well-known/wai-license.json', async (_req, res) => {
+  const handler = connector.handlers.manifest();
+  const resp = handler();
+  res.status(resp.status).json(await resp.json());
+});
+
+// Action endpoints — Wai License calls these when executing sync jobs
+app.post('/wai/licenses/activate', async (req, res) => {
+  const { payload } = req.body as { payload: { licenseKey: string; customerId: string } };
+  // ... activate the license in ALCYA ...
+  res.json({ success: true, licenseKey: payload.licenseKey });
+});
+
+app.post('/wai/customers', async (req, res) => {
+  const { payload } = req.body as { payload: { email: string; name: string } };
+  // ... create the customer in ALCYA ...
+  res.json({ success: true, customerId: 'cust_xxx' });
+});
+
+app.listen(3000, async () => {
+  await connector.start();
+});
+```
+
+---
+
+## TFC Platform Integration Example
+
+TFC Platform is a multi-tenant billing platform that connects with Wai License to manage enterprise licenses:
+
+```ts
+// connector/index.ts
+import { WaiConnector } from '@wai-license/connector-sdk';
+import Hono from 'hono';
+
+const wai = new WaiConnector({
+  connectorCode: 'tfc-platform',
+  connectorName: 'TFC Platform',
+  connectorVersion: '2.1.0',
+  connectorType: 'webhook',
+  waiUrl: process.env.WAI_LICENSE_URL!,
+  apiKey: process.env.WAI_LICENSE_KEY!,
+  capabilities: ['customers', 'licenses', 'billing'],
+  actions: [
+    { code: 'provision_license',  name: 'Provision License',  endpoint: { url: '/webhooks/wai/provision' } },
+    { code: 'revoke_license',     name: 'Revoke License',     endpoint: { url: '/webhooks/wai/revoke' } },
+    { code: 'sync_customer',      name: 'Sync Customer',      endpoint: { url: '/webhooks/wai/customers/sync' } },
+    { code: 'update_plan',        name: 'Update Plan',        endpoint: { url: '/webhooks/wai/plans/update' } },
+  ],
+  heartbeatIntervalMs: 60_000,
+  instanceFilePath: '/data/persistent/.wai-connector.json', // persisted volume
+});
+
+const app = new Hono();
+
+// Discovery manifest
+app.get('/.well-known/wai-license.json', async (c) => {
+  const handler = wai.handlers.manifest();
+  const resp = handler();
+  return c.json(await resp.json(), resp.status as 200);
+});
+
+// Webhook handlers — Wai License POSTs events here
+app.post('/webhooks/wai/provision', async (c) => {
+  const body = await c.req.json() as { payload: unknown };
+  // ... provision the license in TFC ...
+  return c.json({ provisioned: true });
+});
+
+app.post('/webhooks/wai/revoke', async (c) => {
+  const body = await c.req.json() as { payload: unknown };
+  // ... revoke the license ...
+  return c.json({ revoked: true });
+});
+
+export default {
+  fetch: app.fetch,
+  async scheduled() {
+    await wai.fetchConfiguration();
+  },
+};
+
+// Start the connector once the Hono server is ready
+await wai.start();
+```
+
+---
+
+## API Reference
+
+### `new WaiConnector(options)`
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `connectorCode` | `string` | Yes | — | Stable connector identifier |
+| `connectorName` | `string` | Yes | — | Human-readable name |
+| `connectorVersion` | `string` | Yes | — | SemVer string |
+| `connectorType` | `string` | Yes | — | `api` or `webhook` |
+| `waiUrl` | `string` | Yes | — | Base URL of the Wai License server |
+| `apiKey` | `string` | Yes | — | Project API key (`wl_...`) |
+| `capabilities` | `string[]` | Yes | — | List of capability keys |
+| `actions` | `ConnectorActionDefinition[]` | Yes | — | Actions exposed to Wai License |
+| `heartbeatIntervalMs` | `number` | No | `60000` | Heartbeat frequency |
+| `timeoutMs` | `number` | No | `10000` | HTTP request timeout |
+| `instanceFilePath` | `string` | No | `.wai-connector.json` | Instance identity persistence path |
+| `onRegister` | `(ctx: RegisterContext) => void` | No | — | Called on successful registration |
+| `onHeartbeat` | `(ctx: HeartbeatContext) => void` | No | — | Called after each heartbeat |
+| `onConfiguration` | `(ctx: ConfigurationContext) => void` | No | — | Called when config is refreshed |
+| `onError` | `(err: WaiConnectorError) => void` | No | — | Called on any SDK error |
+
+### Instance methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `start()` | `Promise<void>` | Register, heartbeat, and start the loop |
+| `stop()` | `Promise<void>` | Stop the heartbeat timer |
+| `getManifest()` | `WaiManifest` | Manifest object for `/.well-known/wai-license.json` |
+| `getConfiguration()` | `Record<string, unknown>` | Last-known config from Wai License |
+| `fetchConfiguration()` | `Promise<Record<string, unknown>>` | Fetch fresh config now |
+| `handlers.manifest()` | `ConnectorHandler` | Framework-agnostic manifest HTTP handler |
+| `handlers.register()` | `ConnectorHandler` | Framework-agnostic register handler |
+| `handlers.heartbeat()` | `ConnectorHandler` | Framework-agnostic heartbeat handler |
+| `handlers.config()` | `ConnectorHandler` | Framework-agnostic config handler |
+
+### Accessors
+
+| Getter | Type | Description |
+|--------|------|-------------|
+| `instanceId` | `string \| null` | Set after `start()` |
+| `isStarted` | `boolean` | Whether the connector is running |
+
+---
+
+## Instance Identity
+
+Each running process is assigned a stable UUID that persists between restarts. It is stored in `.wai-connector.json` in the current working directory by default.
+
+```json
+{ "instanceId": "550e8400-e29b-41d4-a716-446655440000" }
+```
+
+To use a custom path (e.g. a mounted persistent volume):
+
+```ts
+new WaiConnector({ instanceFilePath: '/data/.wai-connector.json', ...opts });
+```
+
+The SDK is fault-tolerant: if the file cannot be written (read-only filesystem, missing permissions), a UUID is still generated for the session lifetime and the failure is silently ignored.
+
+---
+
+## Error Handling
+
+All errors extend `WaiConnectorError`:
+
+| Class | `statusCode` | When |
+|-------|-------------|------|
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `RegistrationError` | HTTP status | Registration rejected |
+| `HeartbeatError` | HTTP status | Heartbeat rejected |
+| `ConfigurationError` | HTTP status | Config fetch failed |
+| `NetworkError` | 0 | Timeout, DNS failure, connection refused |
+
+```ts
+import { WaiConnector, AuthenticationError, NetworkError } from '@wai-license/connector-sdk';
+
+try {
+  await connector.start();
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    // Check WAI_API_KEY in your environment
+  } else if (err instanceof NetworkError) {
+    // Wai License is unreachable
+  }
+}
+```
+
+---
+
+## Security
+
+- The `apiKey` is sent as a Bearer token in the HTTP `Authorization` header — it is **never** included in request bodies, error messages, or logs.
+- Instance identity (`instanceId`) is safe to log — it contains no sensitive information.
+- The SDK never logs authorization headers or API keys at any log level.
+
+---
+
+## License
+
+Proprietary — Wai License internal package.

package/dist/cjs/client.d.ts

@@ -0,0 +1,10 @@
+import type { RequestOptions } from './types';
+/**
+ * Low-level HTTP transport for Wai License API calls.
+ * Uses native fetch — no axios, no external HTTP libraries.
+ * Never logs the Authorization header or raw apiKey.
+ *
+ * @internal
+ */
+export declare function apiRequest<T>(opts: RequestOptions): Promise<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CA+CpE"}

package/dist/cjs/client.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiRequest = apiRequest;
+const errors_1 = require("./errors");
+/**
+ * Low-level HTTP transport for Wai License API calls.
+ * Uses native fetch — no axios, no external HTTP libraries.
+ * Never logs the Authorization header or raw apiKey.
+ *
+ * @internal
+ */
+async function apiRequest(opts) {
+    const url = `${opts.waiUrl.replace(/\/$/, '')}${opts.path}`;
+    const headers = {
+        Authorization: `Bearer ${opts.apiKey}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), opts.timeoutMs);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: opts.method,
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const isTimeout = err instanceof Error && err.name === 'AbortError';
+        throw new errors_1.NetworkError(isTimeout
+            ? `Request timed out after ${opts.timeoutMs}ms`
+            : `Network error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+    if (response.ok) {
+        const text = await response.text();
+        return (text ? JSON.parse(text) : {});
+    }
+    let errorMessage = `HTTP ${response.status}`;
+    try {
+        const payload = (await response.json());
+        if (typeof payload['message'] === 'string')
+            errorMessage = payload['message'];
+        else if (typeof payload['error'] === 'string')
+            errorMessage = payload['error'];
+    }
+    catch {
+        // non-JSON error body
+    }
+    throw (0, errors_1.createConnectorError)(response.status, errorMessage);
+}
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":";;AAUA,gCA+CC;AAzDD,qCAA8D;AAG9D;;;;;;GAMG;AACI,KAAK,UAAU,UAAU,CAAI,IAAoB;IACtD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAE5D,MAAM,OAAO,GAA2B;QACtC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;QACtC,cAAc,EAAE,kBAAkB;QAClC,MAAM,EAAE,kBAAkB;KAC3B,CAAC;IAEF,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAEvE,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC1B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;YACrE,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,YAAY,CAAC,SAAS,CAAC,CAAC;QACxB,MAAM,SAAS,GAAG,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC;QACpE,MAAM,IAAI,qBAAY,CACpB,SAAS;YACP,CAAC,CAAC,2BAA2B,IAAI,CAAC,SAAS,IAAI;YAC/C,CAAC,CAAC,kBAAkB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACzE,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,SAAS,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAM,CAAC;IAC7C,CAAC;IAED,IAAI,YAAY,GAAG,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC7C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA4B,CAAC;QACnE,IAAI,OAAO,OAAO,CAAC,SAAS,CAAC,KAAK,QAAQ;YAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;aACzE,IAAI,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,QAAQ;YAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,CAAC;IAAC,MAAM,CAAC;QACP,sBAAsB;IACxB,CAAC;IAED,MAAM,IAAA,6BAAoB,EAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAC5D,CAAC"}

package/dist/cjs/configuration.d.ts

@@ -0,0 +1,26 @@
+import type { ConfigurationContext } from './types';
+export interface ConfigurationParams {
+    waiUrl: string;
+    apiKey: string;
+    connectorCode: string;
+    instanceId: string;
+    timeoutMs: number;
+}
+/**
+ * In-memory configuration store.
+ * Updated whenever getConfiguration() is called successfully.
+ *
+ * @internal
+ */
+export declare class ConfigurationStore {
+    private _config;
+    get(): Record<string, unknown>;
+    set(config: Record<string, unknown>): void;
+}
+/**
+ * Fetches the latest connector configuration from the Wai License server.
+ * Calls GET /connectors/config with Bearer auth.
+ * Stores the result in the provided ConfigurationStore.
+ */
+export declare function getConfiguration(params: ConfigurationParams, store: ConfigurationStore): Promise<ConfigurationContext>;
+//# sourceMappingURL=configuration.d.ts.map

package/dist/cjs/configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/configuration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAA+B;IAE9C,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI9B,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAG3C;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,oBAAoB,CAAC,CAkB/B"}

package/dist/cjs/configuration.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigurationStore = void 0;
+exports.getConfiguration = getConfiguration;
+const client_1 = require("./client");
+const errors_1 = require("./errors");
+/**
+ * In-memory configuration store.
+ * Updated whenever getConfiguration() is called successfully.
+ *
+ * @internal
+ */
+class ConfigurationStore {
+    _config = {};
+    get() {
+        return { ...this._config };
+    }
+    set(config) {
+        this._config = { ...config };
+    }
+}
+exports.ConfigurationStore = ConfigurationStore;
+/**
+ * Fetches the latest connector configuration from the Wai License server.
+ * Calls GET /connectors/config with Bearer auth.
+ * Stores the result in the provided ConfigurationStore.
+ */
+async function getConfiguration(params, store) {
+    let config;
+    try {
+        config = await (0, client_1.apiRequest)({
+            waiUrl: params.waiUrl,
+            apiKey: params.apiKey,
+            timeoutMs: params.timeoutMs,
+            path: `/connectors/config?connectorCode=${encodeURIComponent(params.connectorCode)}&instanceId=${encodeURIComponent(params.instanceId)}`,
+            method: 'GET',
+        });
+    }
+    catch (err) {
+        const base = err;
+        throw (0, errors_1.createConnectorError)(base.statusCode ?? 0, base.message, 'configuration');
+    }
+    store.set(config);
+    const fetchedAt = new Date().toISOString();
+    return { config, fetchedAt };
+}
+//# sourceMappingURL=configuration.js.map

package/dist/cjs/configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.js","sourceRoot":"","sources":["../../src/configuration.ts"],"names":[],"mappings":";;;AAmCA,4CAqBC;AAxDD,qCAAsC;AACtC,qCAAgD;AAWhD;;;;;GAKG;AACH,MAAa,kBAAkB;IACrB,OAAO,GAA4B,EAAE,CAAC;IAE9C,GAAG;QACD,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAED,GAAG,CAAC,MAA+B;QACjC,IAAI,CAAC,OAAO,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC/B,CAAC;CACF;AAVD,gDAUC;AAED;;;;GAIG;AACI,KAAK,UAAU,gBAAgB,CACpC,MAA2B,EAC3B,KAAyB;IAEzB,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAA,mBAAU,EAA0B;YACjD,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,IAAI,EAAE,oCAAoC,kBAAkB,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,kBAAkB,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE;YACxI,MAAM,EAAE,KAAK;SACd,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,GAA+C,CAAC;QAC7D,MAAM,IAAA,6BAAoB,EAAC,IAAI,CAAC,UAAU,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAClF,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/B,CAAC"}

package/dist/cjs/connector.d.ts

@@ -0,0 +1,63 @@
+import type { WaiManifest } from './manifest';
+import type { WaiConnectorOptions, ConnectorHandlers } from './types';
+/**
+ * Main entry point for the Wai License Connector SDK.
+ *
+ * @example
+ * ```ts
+ * const connector = new WaiConnector({
+ *   connectorCode: 'alcya',
+ *   connectorName: 'ALCYA',
+ *   connectorVersion: '1.0.0',
+ *   connectorType: 'api',
+ *   waiUrl: process.env.WAI_URL!,
+ *   apiKey: process.env.WAI_API_KEY!,
+ *   capabilities: ['customers', 'licenses'],
+ *   actions: [
+ *     { code: 'activate_license', name: 'Activate License', endpoint: { url: '/wai/licenses/activate' } },
+ *   ],
+ * });
+ *
+ * await connector.start();
+ * ```
+ */
+export declare class WaiConnector {
+    private readonly opts;
+    private _instanceId;
+    private _heartbeatHandle;
+    private _started;
+    private readonly _configStore;
+    constructor(options: WaiConnectorOptions);
+    /**
+     * Loads the instance identity, registers with Wai License,
+     * sends the first heartbeat, then starts the heartbeat loop.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the heartbeat timer. Safe to call multiple times.
+     */
+    stop(): Promise<void>;
+    /** Returns the connector manifest that Wai License reads from /.well-known/wai-license.json */
+    getManifest(): WaiManifest;
+    /** Returns the last-known configuration fetched from Wai License. */
+    getConfiguration(): Record<string, unknown>;
+    /** Fetches fresh configuration from Wai License and updates the in-memory store. */
+    fetchConfiguration(): Promise<Record<string, unknown>>;
+    /**
+     * Returns framework-agnostic HTTP handler functions.
+     * Each handler accepts an optional Request and returns a Response.
+     *
+     * @example Express
+     * ```ts
+     * app.get('/.well-known/wai-license.json', (req, res) => {
+     *   const response = connector.handlers.manifest()(req as unknown as Request);
+     *   res.json(JSON.parse(/* body *\/));
+     * });
+     * ```
+     */
+    get handlers(): ConnectorHandlers;
+    get instanceId(): string | null;
+    get isStarted(): boolean;
+    private static _validate;
+}
+//# sourceMappingURL=connector.d.ts.map

package/dist/cjs/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../src/connector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAElB,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAYnB;IAEF,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,gBAAgB,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA4B;gBAE7C,OAAO,EAAE,mBAAmB;IAwBxC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA8C5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,+FAA+F;IAC/F,WAAW,IAAI,WAAW;IAa1B,qEAAqE;IACrE,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI3C,oFAAoF;IAC9E,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAuB5D;;;;;;;;;;;OAWG;IACH,IAAI,QAAQ,IAAI,iBAAiB,CAuChC;IAID,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAE9B;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAID,OAAO,CAAC,MAAM,CAAC,SAAS;CA0BzB"}