@sippulse/niva-sdk 0.1.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,61 @@
1
+ import { type NivaWebhookHandler, type NivaWebhookHandlerOptions } from "./handler.js";
2
+ export interface NivaWebhookServeOptions {
3
+ port?: number;
4
+ hostname?: string;
5
+ /**
6
+ * Bounded wait for in-flight handlers on close() before the forced stage
7
+ * (abort + connection hammer). Defaults to SHUTDOWN_GRACE_MS (5000 ms).
8
+ * Non-finite or negative values fall back to the default.
9
+ */
10
+ shutdownGraceMs?: number;
11
+ }
12
+ export interface NivaWebhookServerAddress {
13
+ port: number;
14
+ url: string;
15
+ close(): Promise<void>;
16
+ }
17
+ export type NivaWebhookFetch = (request: Request) => Promise<Response>;
18
+ /** A native `serve` implementation: takes the universal fetch, serves it. */
19
+ export type NivaWebhookServerAdapter = (fetch: NivaWebhookFetch, opts: {
20
+ port: number;
21
+ hostname: string;
22
+ shutdownGraceMs: number;
23
+ }) => Promise<NivaWebhookServerAddress>;
24
+ export interface NivaWebhookServer extends NivaWebhookHandler {
25
+ serve(options?: NivaWebhookServeOptions): Promise<NivaWebhookServerAddress>;
26
+ }
27
+ /** Bounded grace for in-flight handlers between close() and the forced stage. */
28
+ export declare const SHUTDOWN_GRACE_MS = 5000;
29
+ /**
30
+ * Settle margin past the grace deadline: the forced stage (abort + hammer)
31
+ * fires, then close() resolves without waiting for stragglers. Runtimes
32
+ * whose drain callback cannot be trusted with a stuck handler (observed:
33
+ * a graceful stop followed by a forced one never resolving) are raced
34
+ * against this margin.
35
+ */
36
+ export declare const SHUTDOWN_SETTLE_MS = 200;
37
+ /** Async sleep for shutdown polling loops (all three runtimes provide setTimeout). */
38
+ export declare function delayMs(ms: number): Promise<void>;
39
+ /**
40
+ * Tracks in-flight webhook dispatches across close(). Adapters admit one
41
+ * request at a time through `admit()` and release it when done; past the
42
+ * grace period `abortInFlight()` aborts every straggler so handlers observe
43
+ * `context.signal` aborted at the forced stage — and only then.
44
+ */
45
+ export interface ShutdownTracker {
46
+ readonly shuttingDown: boolean;
47
+ readonly inFlight: number;
48
+ beginShutdown(): void;
49
+ /** One in-flight slot, or undefined when the server no longer admits. */
50
+ admit(): AbortController | undefined;
51
+ release(controller: AbortController): void;
52
+ abortInFlight(): void;
53
+ }
54
+ export declare function createShutdownTracker(): ShutdownTracker;
55
+ /**
56
+ * The request as the handler must see it: aborted when the client goes away
57
+ * OR when a forced shutdown aborts the in-flight slot.
58
+ */
59
+ export declare function withShutdownSignal(request: Request, signal: AbortSignal): Request;
60
+ /** Compose a handler with a native adapter. `close()` is idempotent per adapter. */
61
+ export declare function defineNivaWebhookServer(options: NivaWebhookHandlerOptions, adapter: NivaWebhookServerAdapter): NivaWebhookServer;
@@ -0,0 +1,17 @@
1
+ import { type NivaWebhookEvent } from "../generated/webhooks.js";
2
+ export declare const DEFAULT_TOLERANCE_SECONDS = 300;
3
+ /** Headers as a `Headers` instance or a plain (possibly mixed-case) map. */
4
+ export type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
5
+ export interface VerifyNivaWebhookOptions {
6
+ secret: string;
7
+ headers: WebhookHeaders;
8
+ body: Uint8Array | ArrayBuffer | string;
9
+ toleranceSeconds?: number;
10
+ /** Unix seconds; defaults to the current time. Injected by tests. */
11
+ now?: number;
12
+ }
13
+ /**
14
+ * Verify a delivery and return the narrowed event. Throws NivaWebhookError
15
+ * with kind + machine code; the error carries no secret, signature, or body.
16
+ */
17
+ export declare function verifyNivaWebhook(options: VerifyNivaWebhookOptions): Promise<NivaWebhookEvent>;