@dszp/netsapiens-lib 0.1.5 → 0.1.7

package/README.md

@@ -72,6 +72,32 @@ than by convention. Writes live in a **separate** class — `NsWriteClient`, a s
 surface (device provisioning) — never as new methods on `NsClient`. So a consumer that holds the read
 client still cannot write; that guarantee holds by construction, not by convention.
 
+### Which writes actually confirm: `synchronous`
+
+`synchronous: 'yes'` asks the API to finish the write before replying, so you get **200 with the
+resulting resource inline** — including server-generated fields you could not otherwise learn without a
+second read, a new device's SIP registration password being the worked example. Without it you get
+**202 Accepted** and a bare `{code, message}`.
+
+It is a **per-operation capability, not a global one**: exactly 17 operations declare it in the v2
+specification (core 44.4.10), and almost all of them are creates. Sending it anywhere else is inert —
+NetSapiens ignores unrecognized body fields and still answers 202 — so code that adds it everywhere
+merely *looks* as though its writes are confirmed.
+
+`NsWriteClient` therefore injects the flag only where it is accepted, and exports the table so other
+NetSapiens clients can share one answer instead of each keeping a copy that drifts:
+
+```ts
+import { supportsSynchronous, SYNCHRONOUS_OPERATIONS } from '@dszp/netsapiens-lib';
+
+supportsSynchronous('POST', '/domains/acme.example/users');     // true  — user CREATE
+supportsSynchronous('PUT',  '/domains/acme.example/users/100'); // false — user UPDATE
+```
+
+`path` is the concrete request path relative to `/ns-api/v2`, dynamic segments already URI-encoded.
+The most consequential absence is that **user update** is not on the list even though user create is:
+there is no response that can confirm a user update, so confirm it by reading the record back.
+
 ### Configuration binds to *your* deployment
 
 Two values are required and have no defaults, on purpose — a default would silently bind you to

package/dist/index.d.ts

@@ -17,7 +17,10 @@ export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, f
 export { resolveSvgSize, rasterizerScript } from './raster.js';
 export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray, type NsClientConfig, type FetchSnapshotOptions } from './nsClient.js';
 export { NsWriteClient, type NsWriteClientConfig } from './nsWriteClient.js';
+export { supportsSynchronous, SYNCHRONOUS_OPERATIONS, type SynchronousMethod, type SynchronousOperation, } from './nsSynchronous.js';
+export { ensureNsDevice, generateSipPassword, SIP_PW_FIELD, type NsDeviceWriter, type EnsureNsDeviceOptions, type EnsureNsDeviceResult, } from './nsDevice.js';
 export { NsAuthClient, NsAuthError, type NsAuthClientConfig, type NsTokenResponse } from './nsAuthClient.js';
+export { NsSubscriptionsClient, NsSubscriptionConflictError, SUBSCRIPTION_MODELS, isSubscriptionModel, nsDatetime, parseNsDatetime, subscriptionFromWire, createInputToWire, updateInputToWire, planSubscriptions, type SubscriptionModel, type SubscriptionStatus, type Subscription, type CreateSubscriptionInput, type UpdateSubscriptionInput, type NsSubscriptionsClientConfig, type DesiredSubscription, type SubscriptionAction, type PlanSubscriptionsOptions, } from './nsSubscriptions.js';
 export { verify, validateJwtFormat, extractContext, assertClaims, verifyHs256Signature, normalizeToken, tokenKey, MemoryVerdictCache, type JwtVerdict, type JwtContext, type ClaimExpectations, type VerdictCache, type VerifyOptions, type FormatResult, } from './jwt.js';
 export { type CallSensitivity, needsFreshAuth, SENSITIVITY_NOTE } from './sensitivity.js';
 export { toPrincipal, parseOperator, isResellerScope, isAdminScope, type Principal, type Operator, type Scope, } from './principal.js';

package/dist/index.js

@@ -16,7 +16,10 @@ export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, f
 export { resolveSvgSize, rasterizerScript } from './raster.js';
 export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray } from './nsClient.js';
 export { NsWriteClient } from './nsWriteClient.js';
+export { supportsSynchronous, SYNCHRONOUS_OPERATIONS, } from './nsSynchronous.js';
+export { ensureNsDevice, generateSipPassword, SIP_PW_FIELD, } from './nsDevice.js';
 export { NsAuthClient, NsAuthError } from './nsAuthClient.js';
+export { NsSubscriptionsClient, NsSubscriptionConflictError, SUBSCRIPTION_MODELS, isSubscriptionModel, nsDatetime, parseNsDatetime, subscriptionFromWire, createInputToWire, updateInputToWire, planSubscriptions, } from './nsSubscriptions.js';
 export { verify, validateJwtFormat, extractContext, assertClaims, verifyHs256Signature, normalizeToken, tokenKey, MemoryVerdictCache, } from './jwt.js';
 export { needsFreshAuth, SENSITIVITY_NOTE } from './sensitivity.js';
 export { toPrincipal, parseOperator, isResellerScope, isAdminScope, } from './principal.js';

package/dist/nsClient.d.ts

@@ -7,7 +7,7 @@
  * `fetchDomainSnapshot()` assembles the same `Snapshot` shape the resolver already consumes, so a
  * live domain flows end-to-end: domain + token → Snapshot → resolveFlow → FlowGraph.
  *
- * This tool never writes to NetSapiens — only GET is exposed.
+ * This client never writes — only GET is exposed. Writes live in the separate `NsWriteClient`.
  */
 import type { Rec, Snapshot } from './model.js';
 export declare class NsApiError extends Error {
@@ -29,12 +29,16 @@ export interface NsClientConfig {
     fetchImpl?: typeof fetch;
 }
 /**
- * NS API v2 client — READ-ONLY BY DESIGN (the central gate for this whole tool).
+ * NS API v2 client — READ-ONLY BY DESIGN.
  *
  * The ONLY method is `get()`, which hardcodes `method: 'GET'`. There is deliberately no
- * post/put/delete/patch — the viewer must never mutate NetSapiens. Keep it that way: do not add a
- * mutating method here. Any write capability must be a separate, explicitly-reviewed client, not a
- * quiet addition to this one. This is the single choke point every NS call in the Worker flows through.
+ * post/put/delete/patch. Keep it that way: **do not add a mutating method here.** The point of this
+ * class is that holding one is proof you cannot write — a guarantee by construction, not convention,
+ * and adding a single mutating method destroys it for every consumer at once.
+ *
+ * Writes are a separate, explicitly-imported class: `NsWriteClient` (see `nsWriteClient.ts`). New
+ * write capability extends that one, never this one. `NsSubscriptionsClient` is a third client for
+ * the same reason — its `DELETE` semantics differ from `NsWriteClient`'s.
  */
 /**
  * Reject a `server` that isn't a bare host or `host:port`. A caller that derives `server` from

package/dist/nsClient.js

@@ -7,7 +7,7 @@
  * `fetchDomainSnapshot()` assembles the same `Snapshot` shape the resolver already consumes, so a
  * live domain flows end-to-end: domain + token → Snapshot → resolveFlow → FlowGraph.
  *
- * This tool never writes to NetSapiens — only GET is exposed.
+ * This client never writes — only GET is exposed. Writes live in the separate `NsWriteClient`.
  */
 export class NsApiError extends Error {
     status;
@@ -26,12 +26,16 @@ export class NsApiError extends Error {
     }
 }
 /**
- * NS API v2 client — READ-ONLY BY DESIGN (the central gate for this whole tool).
+ * NS API v2 client — READ-ONLY BY DESIGN.
  *
  * The ONLY method is `get()`, which hardcodes `method: 'GET'`. There is deliberately no
- * post/put/delete/patch — the viewer must never mutate NetSapiens. Keep it that way: do not add a
- * mutating method here. Any write capability must be a separate, explicitly-reviewed client, not a
- * quiet addition to this one. This is the single choke point every NS call in the Worker flows through.
+ * post/put/delete/patch. Keep it that way: **do not add a mutating method here.** The point of this
+ * class is that holding one is proof you cannot write — a guarantee by construction, not convention,
+ * and adding a single mutating method destroys it for every consumer at once.
+ *
+ * Writes are a separate, explicitly-imported class: `NsWriteClient` (see `nsWriteClient.ts`). New
+ * write capability extends that one, never this one. `NsSubscriptionsClient` is a third client for
+ * the same reason — its `DELETE` semantics differ from `NsWriteClient`'s.
  */
 /**
  * Reject a `server` that isn't a bare host or `host:port`. A caller that derives `server` from

package/dist/nsDevice.d.ts

@@ -0,0 +1,89 @@
+/**
+ * NetSapiens device orchestration — ensure a named device exists and hand back its SIP registration
+ * password, optionally rotating it.
+ *
+ * This lives in the library because two separate consumers had grown their own copy of it, and a
+ * divergence between them is expensive: they both provision the same softphone device for the same
+ * extension, and disagreeing about whether to reuse or replace its credentials produces bugs that look
+ * like a phone problem rather than a code problem. One implementation, one set of tests.
+ *
+ * Mechanism only — no policy. The device NAME is a caller-supplied string (a consumer's `<ext><suffix>`
+ * convention is its own business), *whether* creation is permitted is the caller's decision, and *when*
+ * rotation is appropriate is very much the caller's decision. See {@link ensureNsDevice}.
+ */
+import type { Rec } from './model.js';
+/** The NS device field carrying the auto-generated SIP registration password (API v2). */
+export declare const SIP_PW_FIELD = "device-sip-registration-password";
+/** The subset of a write client this needs. Structural, so a consumer can inject a mock or a subset. */
+export interface NsDeviceWriter {
+    getDevices(domain: string, user: string): Promise<Rec[]>;
+    getDevice(domain: string, user: string, device: string): Promise<Rec>;
+    createDevice(domain: string, user: string, device: string, extra?: Rec): Promise<Rec>;
+    updateDevice(domain: string, user: string, device: string, changes: Rec): Promise<Rec>;
+}
+/**
+ * Generate a SIP registration password.
+ *
+ * Alphanumeric only: the value travels through SIP digest auth, device provisioning templates, and
+ * whatever the consuming app stores it in, and punctuation buys no meaningful entropy while risking an
+ * escaping bug in any one of those. Characters are rejection-sampled rather than modulo-reduced, so every
+ * symbol is equally likely.
+ *
+ * **Guarantees at least one uppercase, one lowercase, and one digit** (for `length >= 3`). A uniform draw
+ * from a 62-symbol alphabet omits digits entirely about 3% of the time at length 20, which looks like a
+ * bug to anyone who eyeballs one and can trip a downstream password-complexity rule. The whole candidate
+ * is redrawn until it qualifies — never patched in place, which would bias the positions it patched.
+ */
+export declare function generateSipPassword(length?: number): string;
+export interface EnsureNsDeviceOptions {
+    domain: string;
+    /** The NS user / extension that owns the device. */
+    user: string;
+    /** The device name, e.g. `100r`. */
+    device: string;
+    /**
+     * May this create the device when it is absent? Default `true`. Pass `false` to look without creating —
+     * the result's `password` is then `''` for a missing device, which a caller can treat as "refuse".
+     */
+    mayCreate?: boolean;
+    /**
+     * Replace the password of a device that **already existed**.
+     *
+     * This closes a subtle and genuinely hard-to-diagnose failure: reusing the stored password leaves any
+     * *other* endpoint still holding it with valid credentials for the same address-of-record. Both clients
+     * then register, the most recent wins, and they trade the registration back and forth — intermittent
+     * call failures with nothing obviously wrong in either system.
+     *
+     * Rotate only where something has just declared this device to belong to one client — a deliberate
+     * activation or a first-time provision. **Do not rotate on a per-login or per-request path**: concurrent
+     * runs would churn the credential and can race a re-registration.
+     *
+     * Rotation is **best-effort** and never throws: on failure the result carries the pre-existing password
+     * plus `rotated: false` and `rotateError`, because failing the whole operation over a hardening step
+     * would be worse than the contention it prevents. Notably a NetSapiens release without the device `PUT`
+     * lands here.
+     */
+    rotateExisting?: boolean;
+    /** Length for a rotated password. Default 20. */
+    passwordLength?: number;
+}
+export interface EnsureNsDeviceResult {
+    /** The SIP password to give the client. `''` means "absent and not created" — treat as a refusal. */
+    password: string;
+    /** True when this call created the device. */
+    created: boolean;
+    /** Present only when `rotateExisting` was requested: whether the rotation actually happened. */
+    rotated?: boolean;
+    /** Why rotation failed, when it did. */
+    rotateError?: string;
+}
+/**
+ * Ensure the device exists and return its SIP password.
+ *
+ * Present: read it back with a per-device GET, because a device *list* may omit the password. Absent:
+ * create it (NetSapiens generates the password; a `synchronous` write returns it inline) unless
+ * `mayCreate` is false.
+ *
+ * A newly created device is never rotated — it already has a fresh, exclusive password.
+ */
+export declare function ensureNsDevice(writer: NsDeviceWriter, opts: EnsureNsDeviceOptions): Promise<EnsureNsDeviceResult>;

package/dist/nsDevice.js

@@ -0,0 +1,101 @@
+/** The NS device field carrying the auto-generated SIP registration password (API v2). */
+export const SIP_PW_FIELD = 'device-sip-registration-password';
+const PW_UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const PW_LOWER = 'abcdefghijklmnopqrstuvwxyz';
+const PW_DIGIT = '0123456789';
+const PW_ALPHABET = PW_UPPER + PW_LOWER + PW_DIGIT;
+/** Uniformly-drawn characters from the alphabet, rejection-sampled so no symbol is over-represented. */
+function randomChars(n) {
+    const out = [];
+    const buf = new Uint8Array(n * 2);
+    const limit = Math.floor(256 / PW_ALPHABET.length) * PW_ALPHABET.length; // 248 for a 62-symbol alphabet
+    while (out.length < n) {
+        crypto.getRandomValues(buf);
+        for (const b of buf) {
+            if (b >= limit)
+                continue; // reject, to keep the distribution uniform
+            out.push(PW_ALPHABET[b % PW_ALPHABET.length]);
+            if (out.length === n)
+                break;
+        }
+    }
+    return out;
+}
+const hasEach = (s) => /[A-Z]/.test(s) && /[a-z]/.test(s) && /[0-9]/.test(s);
+/**
+ * Generate a SIP registration password.
+ *
+ * Alphanumeric only: the value travels through SIP digest auth, device provisioning templates, and
+ * whatever the consuming app stores it in, and punctuation buys no meaningful entropy while risking an
+ * escaping bug in any one of those. Characters are rejection-sampled rather than modulo-reduced, so every
+ * symbol is equally likely.
+ *
+ * **Guarantees at least one uppercase, one lowercase, and one digit** (for `length >= 3`). A uniform draw
+ * from a 62-symbol alphabet omits digits entirely about 3% of the time at length 20, which looks like a
+ * bug to anyone who eyeballs one and can trip a downstream password-complexity rule. The whole candidate
+ * is redrawn until it qualifies — never patched in place, which would bias the positions it patched.
+ */
+export function generateSipPassword(length = 20) {
+    if (!Number.isInteger(length) || length < 1)
+        throw new Error('generateSipPassword: length must be a positive integer');
+    // Below 3 characters the guarantee is arithmetically impossible; return a uniform draw.
+    if (length < 3)
+        return randomChars(length).join('');
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const candidate = randomChars(length).join('');
+        if (hasEach(candidate))
+            return candidate;
+    }
+    // Unreachable in practice (the odds compound to ~0). Draw one character from each class DIRECTLY —
+    // upper-casing an arbitrary draw is not a guarantee, since upper-casing a digit yields the same digit.
+    const pick = (alphabet) => {
+        const b = new Uint8Array(1);
+        const limit = Math.floor(256 / alphabet.length) * alphabet.length;
+        for (;;) {
+            crypto.getRandomValues(b);
+            if (b[0] < limit)
+                return alphabet[b[0] % alphabet.length];
+        }
+    };
+    return [pick(PW_UPPER), pick(PW_LOWER), pick(PW_DIGIT), ...randomChars(length - 3)].join('');
+}
+/**
+ * Ensure the device exists and return its SIP password.
+ *
+ * Present: read it back with a per-device GET, because a device *list* may omit the password. Absent:
+ * create it (NetSapiens generates the password; a `synchronous` write returns it inline) unless
+ * `mayCreate` is false.
+ *
+ * A newly created device is never rotated — it already has a fresh, exclusive password.
+ */
+export async function ensureNsDevice(writer, opts) {
+    const { domain, user, device } = opts;
+    const devices = await writer.getDevices(domain, user);
+    const existing = Array.isArray(devices) ? devices.find((d) => String(d['device'] ?? '') === device) : undefined;
+    if (existing) {
+        const dev = await writer.getDevice(domain, user, device);
+        const current = String(dev[SIP_PW_FIELD] ?? existing[SIP_PW_FIELD] ?? '');
+        if (!opts.rotateExisting)
+            return { password: current, created: false };
+        const fresh = generateSipPassword(opts.passwordLength ?? 20);
+        try {
+            const updated = await writer.updateDevice(domain, user, device, { [SIP_PW_FIELD]: fresh });
+            // Prefer what NS echoes back if it echoes anything; otherwise the value we just set.
+            // `||` not `??`: an echoed empty string would otherwise be handed back as the password, and the
+            // caller's blank-password guard would refuse AFTER the device was already rotated.
+            return { password: String(updated?.[SIP_PW_FIELD] || fresh), created: false, rotated: true };
+        }
+        catch (e) {
+            return {
+                password: current,
+                created: false,
+                rotated: false,
+                rotateError: String(e?.message ?? e).slice(0, 200),
+            };
+        }
+    }
+    if (opts.mayCreate === false)
+        return { password: '', created: false };
+    const created = await writer.createDevice(domain, user, device);
+    return { password: String(created?.[SIP_PW_FIELD] ?? ''), created: true };
+}

package/dist/nsSubscriptions.d.ts

@@ -0,0 +1,268 @@
+/**
+ * NetSapiens API v2 **Event Subscriptions** — a separate client for the `/subscriptions` surface, plus a
+ * pure reconciliation planner.
+ *
+ * This is its own class on purpose. `NsClient` is read-only by charter (a consumer holds one precisely to
+ * know it cannot write), and `NsWriteClient`'s `delete()` sends no body — while
+ * `DELETE /subscriptions/{id}` *requires* one (`subscription_id`, plus `domain` for scopes below Super
+ * User). (A second reason applied until 0.1.7: `NsWriteClient` injected `synchronous: 'yes'` into *every*
+ * POST/PUT, which no `/subscriptions` operation accepts. It now injects only where the API declares
+ * support, so that objection is gone — the `delete()` body is what still makes the split necessary.)
+ * Node-free (fetch/URL/crypto only), so it runs unchanged in a Cloudflare Worker.
+ *
+ * An event subscription tells NetSapiens to POST change events to a URL you own. Notable API properties
+ * that shape this module:
+ *
+ * - **`id` is server-generated**, so a subscription cannot be tagged by the client. Ours are therefore
+ *   identified by `post-url`, which makes the URL both the address *and* the label.
+ * - **Filters are immutable.** `PUT` accepts `post-url` and `subscription-expires-datetime` but not
+ *   `domain`/`user`/`reseller`, so a filter change means a new subscription.
+ * - **Always send an explicit `expiresAt`.** Observed behaviour: an explicit expiry is stored verbatim
+ *   *even when the request is authenticated with a one-hour OAuth access token* — the expiry is not
+ *   clamped to the credential's lifetime. Omitting it yields a ~20-year expiry for an API key but only the
+ *   token's expiry for a timed token, so relying on the default makes lifetime depend on how you
+ *   authenticated. Renewal, when needed, is a `PUT`, never delete-and-recreate.
+ * - ⚠️ **`subscription-geo-support` behaves as `no` when omitted**, despite the API describing the default
+ *   as `yes`. Send it explicitly if you want geo-redundant delivery (you almost certainly do — otherwise
+ *   delivery is pinned and stops when that node is down).
+ * - ⚠️ **The domain-scoped routes (`/domains/{domain}/subscriptions`, API v45+) are not present on every
+ *   cluster** — a v44 cluster answers `404 No Route Found` while the flat `/subscriptions` paths work.
+ *   Prefer the flat methods and treat the domain-scoped ones as an opt-in optimization.
+ * - **Datetimes are asymmetric.** Reads observably return ISO-8601 with an offset; the documented *write*
+ *   format is `YYYY-MM-DD HH:MM:SS`. {@link parseNsDatetime} accepts both; {@link nsDatetime} emits the
+ *   documented form.
+ * - **`error-count` > 0 is normal on a healthy subscription** — a live example sat at 7 errors across 7195
+ *   posts while `status` stayed `active`. Treat `status === 'error'` or a sustained error *rate* as the
+ *   signal, and never reset the counters as routine maintenance: they are the only history the API keeps.
+ */
+import type { Rec } from './model.js';
+import { NsApiError } from './nsClient.js';
+/** Event types a subscription can carry. One subscription carries exactly one model. */
+export type SubscriptionModel = 'agent' | 'auditlog' | 'auditlog_lite' | 'call' | 'call_origid' | 'cdr' | 'message' | 'messagesession' | 'subscriber' | 'presence' | 'voicemail';
+/** Every valid `model` value, for validating configuration before it reaches the API. */
+export declare const SUBSCRIPTION_MODELS: readonly SubscriptionModel[];
+/** Narrowing guard for a configured model string. */
+export declare function isSubscriptionModel(v: unknown): v is SubscriptionModel;
+/** Server-reported delivery health. `pending` until the first successful post. */
+export type SubscriptionStatus = 'pending' | 'active' | 'error';
+/**
+ * A subscription, with the API's hyphenated wire keys mapped to camelCase. Datetimes are kept as the
+ * **raw strings** the API returned (parse with {@link parseNsDatetime} when you need a `Date`), and `raw`
+ * carries the untouched record so a caller never loses a field this type hasn't modelled.
+ */
+export interface Subscription {
+    id: string;
+    model?: string;
+    postUrl?: string;
+    geoSupport?: string;
+    userScope?: string;
+    reseller?: string;
+    domain?: string;
+    user?: string;
+    /** Raw `subscription-creation-datetime`. */
+    createdAt?: string;
+    /** Raw `subscription-expires-datetime`. */
+    expiresAt?: string;
+    preferredServer?: string;
+    /** Read-only: the node currently delivering. Changes on failover. */
+    currentActiveServer?: string;
+    status?: string;
+    errorCount?: number;
+    postsCount?: number;
+    /** The untouched API record. */
+    raw: Rec;
+}
+/** Fields accepted when creating. `domain`/`user`/`reseller` are the (immutable) event filters. */
+export interface CreateSubscriptionInput {
+    model: SubscriptionModel;
+    /** Absolute https URL NetSapiens will POST to. */
+    postUrl: string;
+    /** Restrict to one domain. `'*'` means all domains and requires Super User scope. */
+    domain?: string;
+    /** Restrict to one user/extension. Defaults to all. */
+    user?: string;
+    /** Restrict to one reseller. `'*'` requires Super User scope. */
+    reseller?: string;
+    /**
+     * Geo-redundant delivery across nodes. ⚠️ Behaves as `'no'` when omitted, despite the API documenting
+     * `'yes'` as the default — send `'yes'` explicitly unless you deliberately want delivery pinned.
+     */
+    geoSupport?: 'yes' | 'no';
+    /**
+     * Explicit expiry, and you should always set one. It is honoured verbatim even when the request is
+     * authenticated with a short-lived OAuth token. Omitting it makes the lifetime depend on the credential
+     * (API key ⇒ ~20 years; timed token ⇒ that token's expiry).
+     */
+    expiresAt?: Date | string;
+    /** Preferred delivering node. A preference, not a pin — other nodes deliver during instability. */
+    preferredServer?: string;
+}
+/** Fields `PUT` accepts. The event filters are deliberately absent — they cannot be changed. */
+export interface UpdateSubscriptionInput {
+    model?: SubscriptionModel;
+    postUrl?: string;
+    geoSupport?: 'yes' | 'no';
+    expiresAt?: Date | string;
+    preferredServer?: string;
+    /** Only `0` is accepted — a reset. Prefer leaving counters alone; they are the only history kept. */
+    errorCount?: 0;
+    /** Only `0` is accepted — a reset. */
+    postsCount?: 0;
+}
+/**
+ * Format a `Date` as the documented write format `YYYY-MM-DD HH:MM:SS`, **in UTC**.
+ *
+ * The API documents no timezone for this field. Emitting UTC is the only self-consistent choice, and it
+ * round-trips with {@link parseNsDatetime}, which also reads a bare timestamp as UTC.
+ */
+export declare function nsDatetime(d: Date): string;
+/**
+ * Parse either datetime shape the API uses: the documented `YYYY-MM-DD HH:MM:SS` (read as **UTC**) or the
+ * ISO-8601-with-offset form that reads actually return. Returns `undefined` rather than an Invalid Date so
+ * callers fail closed on a value they can't interpret.
+ */
+export declare function parseNsDatetime(s: string | undefined | null): Date | undefined;
+/** Map one API record to {@link Subscription}. Tolerant: an unmodelled or missing field is simply absent. */
+export declare function subscriptionFromWire(rec: Rec): Subscription;
+/** Map {@link CreateSubscriptionInput} to the hyphenated request body. */
+export declare function createInputToWire(input: CreateSubscriptionInput): Rec;
+/** Map {@link UpdateSubscriptionInput} to the hyphenated request body. */
+export declare function updateInputToWire(changes: UpdateSubscriptionInput): Rec;
+export interface NsSubscriptionsClientConfig {
+    /** API host, e.g. `"api.example.com"`. Base URL becomes `https://{server}/ns-api/v2`. */
+    server: string;
+    /** Bearer token — an API key, or an OAuth access token, with scope to manage subscriptions. */
+    token: string;
+    /** Injectable for tests / non-global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Page size for list calls. Default 500. */
+    pageSize?: number;
+}
+/** Thrown by {@link NsSubscriptionsClient.create} on the API's 409 "already exists" response. */
+export declare class NsSubscriptionConflictError extends NsApiError {
+    constructor(message: string, path: string, body: unknown);
+}
+/**
+ * Read/write client for `/subscriptions`.
+ *
+ * ```ts
+ * const subs = new NsSubscriptionsClient({ server: 'api.example.com', token: key });
+ * const mine = (await subs.list()).filter((s) => s.postUrl?.startsWith('https://hooks.example.com/'));
+ * ```
+ */
+export declare class NsSubscriptionsClient {
+    #private;
+    constructor(cfg: NsSubscriptionsClientConfig);
+    /**
+     * Every subscription the credential can see, paged to completion.
+     *
+     * Paging matters: with no local registry this list *is* the source of truth, so a partial read would
+     * make a reconciler create duplicates or skip renewals. The loop is defensive in both directions — it
+     * stops on a short page, and also if a server that ignores the paging parameters returns the same
+     * records again.
+     */
+    list(): Promise<Subscription[]>;
+    /** Subscriptions filtered to one domain. ⚠️ Requires API v45+; a v44 cluster returns 404. */
+    listForDomain(domain: string): Promise<Subscription[]>;
+    /** Read one subscription by id. */
+    get(id: string): Promise<Subscription>;
+    /**
+     * Create a subscription. Throws {@link NsSubscriptionConflictError} on 409, which the API returns when a
+     * subscription with a matching set of parameters already exists — usually meaning the desired state is
+     * already in place.
+     */
+    create(input: CreateSubscriptionInput): Promise<Subscription>;
+    /** Create against the domain-scoped path. ⚠️ Requires API v45+; a v44 cluster returns 404. */
+    createForDomain(domain: string, input: CreateSubscriptionInput): Promise<Subscription>;
+    /**
+     * Update a subscription — this is how renewal works (a new `subscription-expires-datetime`) and how a
+     * callback URL is rotated (`post-url`). The event filters cannot be changed.
+     */
+    update(id: string, changes: UpdateSubscriptionInput): Promise<unknown>;
+    /** Update against the domain-scoped path. ⚠️ Requires API v45+; a v44 cluster returns 404. */
+    updateForDomain(domain: string, id: string, changes: UpdateSubscriptionInput): Promise<unknown>;
+    /**
+     * Delete a subscription.
+     *
+     * Note the body: this endpoint takes `subscription_id` (and `domain`, required for scopes below Super
+     * User) *in addition to* the path id. That is why this client exists rather than reusing a generic write
+     * client whose `delete()` sends no body.
+     */
+    remove(id: string, opts?: {
+        domain?: string;
+    }): Promise<unknown>;
+}
+/** One subscription we want to exist. */
+export interface DesiredSubscription {
+    domain: string;
+    model: SubscriptionModel;
+    /** The exact callback URL this (domain, model) should post to. */
+    postUrl: string;
+}
+/** An action the caller should execute. Every variant carries a human-readable `reason` for logging. */
+export type SubscriptionAction = {
+    kind: 'create';
+    domain: string;
+    model: SubscriptionModel;
+    postUrl: string;
+    expiresAt: string;
+    reason: string;
+} | {
+    kind: 'renew';
+    id: string;
+    domain: string;
+    expiresAt: string;
+    reason: string;
+} | {
+    kind: 'repair-url';
+    id: string;
+    domain: string;
+    postUrl: string;
+    reason: string;
+} | {
+    kind: 'delete';
+    id: string;
+    domain: string;
+    reason: string;
+} | {
+    kind: 'report';
+    id: string;
+    domain: string;
+    reason: string;
+    status?: string;
+    errorCount?: number;
+    postsCount?: number;
+} | {
+    kind: 'noop';
+    id: string;
+    domain: string;
+    reason: string;
+};
+export interface PlanSubscriptionsOptions {
+    /**
+     * Only subscriptions whose `postUrl` starts with this prefix are considered ours. Everything else is
+     * left strictly alone — other integrations legitimately subscribe to the same domains.
+     */
+    ownedPrefix: string;
+    /** Renew when the remaining lifetime is below this. */
+    renewHorizonSeconds: number;
+    /** Lifetime to request on create and renew. */
+    targetLifetimeSeconds: number;
+    /** Report when `errorCount / postsCount` exceeds this. Default 0.5. */
+    errorRateThreshold?: number;
+    /** Don't judge an error rate below this many posts — small samples are noise. Default 25. */
+    minPostsForRate?: number;
+}
+/**
+ * Decide what to do, given what we want and what the API currently reports. Pure: no I/O, no clock, no
+ * configuration beyond {@link PlanSubscriptionsOptions} — so the whole decision surface is unit-testable
+ * and shareable by any consumer that manages its own subscriptions.
+ *
+ * Deliberate behaviours worth knowing:
+ * - Subscriptions outside `ownedPrefix` are **never** modified. If one collides with a desired
+ *   (domain, model) it is *reported*, because two subscriptions on one domain double-deliver.
+ * - `errorCount > 0` alone is **not** a fault — see this module's header.
+ * - An already-expired subscription yields `renew`, not `delete`+`create`; the caller should fall back to
+ *   `create` only if the `PUT` reports the subscription is gone.
+ */
+export declare function planSubscriptions(desired: DesiredSubscription[], actual: Subscription[], nowMs: number, opts: PlanSubscriptionsOptions): SubscriptionAction[];