@ultdai/pulse 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @ultdai/pulse
+
+Serverové TypeScript SDK pro odesílání pulsů do Unlimited. Funguje i v Cloudflare Workers.
+
+```sh
+npm install @ultdai/pulse
+```
+
+```ts
+import { CloudflareSdkConfigurationCache, UnlimitedClient } from '@ultdai/pulse'
+
+export interface Env { ULTD_API_TOKEN: string }
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const session = getPlaybackSession(request) // stabilní ID a čas vzniku v Unixových milisekundách
+    const client = new UnlimitedClient({
+      apiToken: env.ULTD_API_TOKEN,
+      baseUrl: 'https://api.ultd.tivio.studio',
+      cache: new CloudflareSdkConfigurationCache(caches.default),
+      source: 'stream-worker',
+    })
+    await client.emit({
+      occurredAtMs: Date.now(),
+      organizationId: 'tivio',
+      pulse: {
+        type: 'stream.segment.requested',
+        version: 3,
+        id: session.id,
+        payload: {
+          sessionStartedAtMs: session.startedAtMs,
+          videoId: session.videoId,
+          ...(session.channelId ? { channelId: session.channelId } : {}),
+        },
+      },
+    })
+    return new Response('ok')
+  },
+}
+```
+
+Klíč patří do serverového secretu, nikdy do klientského JavaScriptu. Konstruktor bez neprázdného `apiToken` skončí chybou ještě před síťovým voláním. Unlimited ověřuje klíč znovu na `GET /v1/sdk-config` i `POST /v1/pulses`; neplatný klíč nemůže zapsat puls.
+
+SDK dynamicky načítá seznam PulseTypes, jejich schémata, povolení sběru a sampling politiku při prvním `emit()`. Neznámý typ nebo nevalidní `pulse.payload` SDK odmítne lokálně. Vypnutý nebo nevzorkovaný puls neodešle. `occurredAtMs` a playback v3 `sessionStartedAtMs` jsou Unixové časy v milisekundách. Playback v2 se starším ISO polem `sessionStartedAt` zůstává podporován. Konfigurace má krátkou platnost a po jejím vypršení se obnovuje; pokud obnovení selže, puls se neodešle. Cloudflare cache je volitelná; bez ní SDK používá paměť instance.
+
+SDK obsahuje interní kontrakty přibalené při buildu z monorepa. Aplikace instaluje jen `@ultdai/pulse` a jeho běžnou závislost `zod`; `@ultdai/contracts` se samostatně nevydává. Samotné zveřejnění SDK neposkytuje oprávnění k API.

package/dist/cache.d.ts

@@ -0,0 +1,22 @@
+import type { SamplingPolicy } from './contracts/index.js';
+export interface SamplingPolicyCache {
+    get(key: string): Promise<SamplingPolicy | undefined>;
+    set(key: string, policy: SamplingPolicy): Promise<void>;
+}
+export declare class MemorySamplingPolicyCache implements SamplingPolicyCache {
+    private readonly policies;
+    get(key: string): Promise<SamplingPolicy | undefined>;
+    set(key: string, policy: SamplingPolicy): Promise<void>;
+}
+export interface CacheApiLike {
+    match(request: Request): Promise<Response | undefined>;
+    put(request: Request, response: Response): Promise<void>;
+}
+export declare class CloudflareSamplingPolicyCache implements SamplingPolicyCache {
+    private readonly cache;
+    private readonly namespace;
+    constructor(cache: CacheApiLike, namespace?: string);
+    private request;
+    get(key: string): Promise<SamplingPolicy | undefined>;
+    set(key: string, policy: SamplingPolicy): Promise<void>;
+}

package/dist/configurationCache.d.ts

@@ -0,0 +1,23 @@
+import type { SdkConfiguration } from './contracts/index.js';
+import type { CacheApiLike } from './cache.js';
+export interface CachedSdkConfiguration {
+    configuration: SdkConfiguration;
+    etag: string | null;
+}
+export interface SdkConfigurationCache {
+    get(key: string): Promise<CachedSdkConfiguration | undefined>;
+    set(key: string, value: CachedSdkConfiguration): Promise<void>;
+}
+export declare class MemorySdkConfigurationCache implements SdkConfigurationCache {
+    private readonly values;
+    get(key: string): Promise<CachedSdkConfiguration | undefined>;
+    set(key: string, value: CachedSdkConfiguration): Promise<void>;
+}
+export declare class CloudflareSdkConfigurationCache implements SdkConfigurationCache {
+    private readonly cache;
+    private readonly namespace;
+    constructor(cache: CacheApiLike, namespace?: string);
+    private request;
+    get(key: string): Promise<CachedSdkConfiguration | undefined>;
+    set(key: string, value: CachedSdkConfiguration): Promise<void>;
+}

package/dist/contracts/index.d.ts

@@ -0,0 +1,544 @@
+import { z } from 'zod';
+export { compilePayloadSchema } from './payloadSchema.js';
+export declare const PulseSubjectSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+}, z.core.$strip>;
+export declare const SamplingMethodSchema: z.ZodEnum<{
+    none: "none";
+    "pulse-hash-v1": "pulse-hash-v1";
+}>;
+export declare const SamplingUnitSchema: z.ZodEnum<{
+    member: "member";
+    pulse: "pulse";
+}>;
+export declare const SamplingContextSchema: z.ZodObject<{
+    applied: z.ZodBoolean;
+    appliedKeepProbability: z.ZodNumber;
+    effectiveKeepProbability: z.ZodNumber;
+    ingressApplied: z.ZodBoolean;
+    ingressKeepProbability: z.ZodNumber;
+    ingressMethod: z.ZodEnum<{
+        none: "none";
+        "pulse-hash-v1": "pulse-hash-v1";
+    }>;
+    knownKeepProbability: z.ZodNullable<z.ZodNumber>;
+    method: z.ZodEnum<{
+        none: "none";
+        "pulse-hash-v1": "pulse-hash-v1";
+    }>;
+    policyId: z.ZodNullable<z.ZodString>;
+    policyRevision: z.ZodNullable<z.ZodNumber>;
+    unit: z.ZodEnum<{
+        member: "member";
+        pulse: "pulse";
+    }>;
+}, z.core.$strict>;
+export declare const NoSamplingContext: z.infer<typeof SamplingContextSchema>;
+export declare const PulseInputSchema: z.ZodObject<{
+    data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    eventId: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    organizationId: z.ZodString;
+    occurredAt: z.ZodOptional<z.ZodString>;
+    sampling: z.ZodDefault<z.ZodObject<{
+        applied: z.ZodBoolean;
+        appliedKeepProbability: z.ZodNumber;
+        effectiveKeepProbability: z.ZodNumber;
+        ingressApplied: z.ZodBoolean;
+        ingressKeepProbability: z.ZodNumber;
+        ingressMethod: z.ZodEnum<{
+            none: "none";
+            "pulse-hash-v1": "pulse-hash-v1";
+        }>;
+        knownKeepProbability: z.ZodNullable<z.ZodNumber>;
+        method: z.ZodEnum<{
+            none: "none";
+            "pulse-hash-v1": "pulse-hash-v1";
+        }>;
+        policyId: z.ZodNullable<z.ZodString>;
+        policyRevision: z.ZodNullable<z.ZodNumber>;
+        unit: z.ZodEnum<{
+            member: "member";
+            pulse: "pulse";
+        }>;
+    }, z.core.$strict>>;
+    source: z.ZodString;
+    subject: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    type: z.ZodString;
+    typeVersion: z.ZodNumber;
+}, z.core.$strict>;
+export declare const PulseSubmissionSchema: z.ZodObject<{
+    occurredAtMs: z.ZodNumber;
+    organizationId: z.ZodString;
+    pulse: z.ZodObject<{
+        eventId: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        payload: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        subject: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+        type: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$strict>;
+    sampling: z.ZodDefault<z.ZodObject<{
+        applied: z.ZodBoolean;
+        appliedKeepProbability: z.ZodNumber;
+        effectiveKeepProbability: z.ZodNumber;
+        ingressApplied: z.ZodBoolean;
+        ingressKeepProbability: z.ZodNumber;
+        ingressMethod: z.ZodEnum<{
+            none: "none";
+            "pulse-hash-v1": "pulse-hash-v1";
+        }>;
+        knownKeepProbability: z.ZodNullable<z.ZodNumber>;
+        method: z.ZodEnum<{
+            none: "none";
+            "pulse-hash-v1": "pulse-hash-v1";
+        }>;
+        policyId: z.ZodNullable<z.ZodString>;
+        policyRevision: z.ZodNullable<z.ZodNumber>;
+        unit: z.ZodEnum<{
+            member: "member";
+            pulse: "pulse";
+        }>;
+    }, z.core.$strict>>;
+    source: z.ZodString;
+}, z.core.$strict>;
+export declare const RawPulseSchema: z.ZodObject<{
+    data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    eventId: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    organizationId: z.ZodString;
+    sampling: z.ZodDefault<z.ZodObject<{
+        applied: z.ZodBoolean;
+        appliedKeepProbability: z.ZodNumber;
+        effectiveKeepProbability: z.ZodNumber;
+        ingressApplied: z.ZodBoolean;
+        ingressKeepProbability: z.ZodNumber;
+        ingressMethod: z.ZodEnum<{
+            none: "none";
+            "pulse-hash-v1": "pulse-hash-v1";
+        }>;
+        knownKeepProbability: z.ZodNullable<z.ZodNumber>;
+        method: z.ZodEnum<{
+            none: "none";
+            "pulse-hash-v1": "pulse-hash-v1";
+        }>;
+        policyId: z.ZodNullable<z.ZodString>;
+        policyRevision: z.ZodNullable<z.ZodNumber>;
+        unit: z.ZodEnum<{
+            member: "member";
+            pulse: "pulse";
+        }>;
+    }, z.core.$strict>>;
+    source: z.ZodString;
+    subject: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    type: z.ZodString;
+    typeVersion: z.ZodNumber;
+    occurredAt: z.ZodString;
+    receivedAt: z.ZodString;
+}, z.core.$strict>;
+export declare const PulseDeliverySchema: z.ZodEnum<{
+    live: "live";
+    reliable: "reliable";
+}>;
+export declare const PulseTypeDefinitionSchema: z.ZodObject<{
+    delivery: z.ZodEnum<{
+        live: "live";
+        reliable: "reliable";
+    }>;
+    id: z.ZodString;
+    payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    requiresExplicitId: z.ZodOptional<z.ZodBoolean>;
+    sampling: z.ZodOptional<z.ZodObject<{
+        keyField: z.ZodNullable<z.ZodString>;
+        unit: z.ZodEnum<{
+            member: "member";
+            pulse: "pulse";
+        }>;
+    }, z.core.$strict>>;
+    samplingAllowed: z.ZodBoolean;
+    version: z.ZodNumber;
+}, z.core.$strict>;
+export declare const SignalReducerSchema: z.ZodEnum<{
+    "distinct-per-window": "distinct-per-window";
+    presence: "presence";
+}>;
+export declare const SignalTypeDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    inputPulseTypes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$strict>>;
+    dimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    partitionKey: z.ZodOptional<z.ZodString>;
+    presence: z.ZodOptional<z.ZodObject<{
+        immutableDimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        memberIdField: z.ZodString;
+        startedAtField: z.ZodOptional<z.ZodString>;
+        timeoutMs: z.ZodNumber;
+    }, z.core.$strict>>;
+    reducer: z.ZodEnum<{
+        "distinct-per-window": "distinct-per-window";
+        presence: "presence";
+    }>;
+    shardCount: z.ZodNumber;
+    shardSchedule: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        effectiveFrom: z.ZodString;
+        generation: z.ZodNumber;
+        shardCount: z.ZodNumber;
+    }, z.core.$strict>>>;
+    version: z.ZodNumber;
+    windowMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const MetricPulseTargetSchema: z.ZodObject<{
+    generation: z.ZodNumber;
+    immutableDimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodEnum<{
+        "distinct-per-window": "distinct-per-window";
+        presence: "presence";
+    }>;
+    memberId: z.ZodString;
+    organizationId: z.ZodString;
+    ownerId: z.ZodString;
+    refs: z.ZodArray<z.ZodObject<{
+        signalId: z.ZodString;
+        dimension: z.ZodString;
+    }, z.core.$strict>>;
+    sessionStartedAt: z.ZodString;
+    shardCount: z.ZodNumber;
+    shardIndex: z.ZodNumber;
+    signalTypeId: z.ZodString;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    windowEndAt: z.ZodOptional<z.ZodString>;
+    windowStartAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const RoutedMetricPulseSchema: z.ZodObject<{
+    pulse: z.ZodObject<{
+        data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        eventId: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        organizationId: z.ZodString;
+        sampling: z.ZodDefault<z.ZodObject<{
+            applied: z.ZodBoolean;
+            appliedKeepProbability: z.ZodNumber;
+            effectiveKeepProbability: z.ZodNumber;
+            ingressApplied: z.ZodBoolean;
+            ingressKeepProbability: z.ZodNumber;
+            ingressMethod: z.ZodEnum<{
+                none: "none";
+                "pulse-hash-v1": "pulse-hash-v1";
+            }>;
+            knownKeepProbability: z.ZodNullable<z.ZodNumber>;
+            method: z.ZodEnum<{
+                none: "none";
+                "pulse-hash-v1": "pulse-hash-v1";
+            }>;
+            policyId: z.ZodNullable<z.ZodString>;
+            policyRevision: z.ZodNullable<z.ZodNumber>;
+            unit: z.ZodEnum<{
+                member: "member";
+                pulse: "pulse";
+            }>;
+        }, z.core.$strict>>;
+        source: z.ZodString;
+        subject: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+        type: z.ZodString;
+        typeVersion: z.ZodNumber;
+        occurredAt: z.ZodString;
+        receivedAt: z.ZodString;
+    }, z.core.$strict>;
+    target: z.ZodObject<{
+        generation: z.ZodNumber;
+        immutableDimensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodEnum<{
+            "distinct-per-window": "distinct-per-window";
+            presence: "presence";
+        }>;
+        memberId: z.ZodString;
+        organizationId: z.ZodString;
+        ownerId: z.ZodString;
+        refs: z.ZodArray<z.ZodObject<{
+            signalId: z.ZodString;
+            dimension: z.ZodString;
+        }, z.core.$strict>>;
+        sessionStartedAt: z.ZodString;
+        shardCount: z.ZodNumber;
+        shardIndex: z.ZodNumber;
+        signalTypeId: z.ZodString;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        windowEndAt: z.ZodOptional<z.ZodString>;
+        windowStartAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const MetricSnapshotSchema: z.ZodObject<{
+    estimatedCount: z.ZodNumber;
+    generation: z.ZodNumber;
+    kind: z.ZodEnum<{
+        "distinct-per-window": "distinct-per-window";
+        presence: "presence";
+    }>;
+    observedAt: z.ZodString;
+    organizationId: z.ZodString;
+    originId: z.ZodString;
+    recovering: z.ZodBoolean;
+    revision: z.ZodNumber;
+    sampledCount: z.ZodNumber;
+    shardCount: z.ZodNumber;
+    signalId: z.ZodString;
+    signalTypeId: z.ZodString;
+    windowEndAt: z.ZodOptional<z.ZodString>;
+    windowStartAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const SamplingPolicySchema: z.ZodObject<{
+    expiresAt: z.ZodString;
+    keyField: z.ZodNullable<z.ZodString>;
+    keepProbability: z.ZodNumber;
+    method: z.ZodLiteral<"pulse-hash-v1">;
+    policyId: z.ZodString;
+    pulseTypeId: z.ZodString;
+    pulseTypeVersion: z.ZodNumber;
+    revision: z.ZodNumber;
+    unit: z.ZodEnum<{
+        member: "member";
+        pulse: "pulse";
+    }>;
+}, z.core.$strict>;
+export declare const SdkPulseTypeSchema: z.ZodObject<{
+    definition: z.ZodObject<{
+        delivery: z.ZodEnum<{
+            live: "live";
+            reliable: "reliable";
+        }>;
+        id: z.ZodString;
+        payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        requiresExplicitId: z.ZodOptional<z.ZodBoolean>;
+        sampling: z.ZodOptional<z.ZodObject<{
+            keyField: z.ZodNullable<z.ZodString>;
+            unit: z.ZodEnum<{
+                member: "member";
+                pulse: "pulse";
+            }>;
+        }, z.core.$strict>>;
+        samplingAllowed: z.ZodBoolean;
+        version: z.ZodNumber;
+    }, z.core.$strict>;
+    enabled: z.ZodBoolean;
+    samplingPolicy: z.ZodNullable<z.ZodObject<{
+        expiresAt: z.ZodString;
+        keyField: z.ZodNullable<z.ZodString>;
+        keepProbability: z.ZodNumber;
+        method: z.ZodLiteral<"pulse-hash-v1">;
+        policyId: z.ZodString;
+        pulseTypeId: z.ZodString;
+        pulseTypeVersion: z.ZodNumber;
+        revision: z.ZodNumber;
+        unit: z.ZodEnum<{
+            member: "member";
+            pulse: "pulse";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const SdkConfigurationSchema: z.ZodObject<{
+    expiresAt: z.ZodString;
+    pulseTypes: z.ZodArray<z.ZodObject<{
+        definition: z.ZodObject<{
+            delivery: z.ZodEnum<{
+                live: "live";
+                reliable: "reliable";
+            }>;
+            id: z.ZodString;
+            payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            requiresExplicitId: z.ZodOptional<z.ZodBoolean>;
+            sampling: z.ZodOptional<z.ZodObject<{
+                keyField: z.ZodNullable<z.ZodString>;
+                unit: z.ZodEnum<{
+                    member: "member";
+                    pulse: "pulse";
+                }>;
+            }, z.core.$strict>>;
+            samplingAllowed: z.ZodBoolean;
+            version: z.ZodNumber;
+        }, z.core.$strict>;
+        enabled: z.ZodBoolean;
+        samplingPolicy: z.ZodNullable<z.ZodObject<{
+            expiresAt: z.ZodString;
+            keyField: z.ZodNullable<z.ZodString>;
+            keepProbability: z.ZodNumber;
+            method: z.ZodLiteral<"pulse-hash-v1">;
+            policyId: z.ZodString;
+            pulseTypeId: z.ZodString;
+            pulseTypeVersion: z.ZodNumber;
+            revision: z.ZodNumber;
+            unit: z.ZodEnum<{
+                member: "member";
+                pulse: "pulse";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    revision: z.ZodNumber;
+}, z.core.$strict>;
+export declare const LivePulseTargetSchema: z.ZodObject<{
+    generation: z.ZodNumber;
+    memberId: z.ZodString;
+    organizationId: z.ZodString;
+    reducer: z.ZodEnum<{
+        "distinct-per-window": "distinct-per-window";
+        presence: "presence";
+    }>;
+    shardId: z.ZodString;
+    signalId: z.ZodString;
+    signalTypeId: z.ZodString;
+    signalTypeVersion: z.ZodNumber;
+    timeoutMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const RoutedLivePulseSchema: z.ZodObject<{
+    pulse: z.ZodObject<{
+        data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        eventId: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        organizationId: z.ZodString;
+        sampling: z.ZodDefault<z.ZodObject<{
+            applied: z.ZodBoolean;
+            appliedKeepProbability: z.ZodNumber;
+            effectiveKeepProbability: z.ZodNumber;
+            ingressApplied: z.ZodBoolean;
+            ingressKeepProbability: z.ZodNumber;
+            ingressMethod: z.ZodEnum<{
+                none: "none";
+                "pulse-hash-v1": "pulse-hash-v1";
+            }>;
+            knownKeepProbability: z.ZodNullable<z.ZodNumber>;
+            method: z.ZodEnum<{
+                none: "none";
+                "pulse-hash-v1": "pulse-hash-v1";
+            }>;
+            policyId: z.ZodNullable<z.ZodString>;
+            policyRevision: z.ZodNullable<z.ZodNumber>;
+            unit: z.ZodEnum<{
+                member: "member";
+                pulse: "pulse";
+            }>;
+        }, z.core.$strict>>;
+        source: z.ZodString;
+        subject: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+        type: z.ZodString;
+        typeVersion: z.ZodNumber;
+        occurredAt: z.ZodString;
+        receivedAt: z.ZodString;
+    }, z.core.$strict>;
+    target: z.ZodObject<{
+        generation: z.ZodNumber;
+        memberId: z.ZodString;
+        organizationId: z.ZodString;
+        reducer: z.ZodEnum<{
+            "distinct-per-window": "distinct-per-window";
+            presence: "presence";
+        }>;
+        shardId: z.ZodString;
+        signalId: z.ZodString;
+        signalTypeId: z.ZodString;
+        signalTypeVersion: z.ZodNumber;
+        timeoutMs: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const LiveShardSnapshotSchema: z.ZodObject<{
+    activeCount: z.ZodNumber;
+    estimatedActiveCount: z.ZodNumber;
+    observedAt: z.ZodString;
+    organizationId: z.ZodString;
+    recovering: z.ZodBoolean;
+    revision: z.ZodNumber;
+    shardId: z.ZodString;
+    signalId: z.ZodString;
+    signalTypeId: z.ZodString;
+}, z.core.$strict>;
+export declare const PulseAggregateSchema: z.ZodObject<{
+    aggregationKey: z.ZodString;
+    count: z.ZodNumber;
+    createdAt: z.ZodString;
+    id: z.ZodString;
+    organizationId: z.ZodString;
+    pulses: z.ZodArray<z.ZodObject<{
+        data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        eventId: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        organizationId: z.ZodString;
+        sampling: z.ZodDefault<z.ZodObject<{
+            applied: z.ZodBoolean;
+            appliedKeepProbability: z.ZodNumber;
+            effectiveKeepProbability: z.ZodNumber;
+            ingressApplied: z.ZodBoolean;
+            ingressKeepProbability: z.ZodNumber;
+            ingressMethod: z.ZodEnum<{
+                none: "none";
+                "pulse-hash-v1": "pulse-hash-v1";
+            }>;
+            knownKeepProbability: z.ZodNullable<z.ZodNumber>;
+            method: z.ZodEnum<{
+                none: "none";
+                "pulse-hash-v1": "pulse-hash-v1";
+            }>;
+            policyId: z.ZodNullable<z.ZodString>;
+            policyRevision: z.ZodNullable<z.ZodNumber>;
+            unit: z.ZodEnum<{
+                member: "member";
+                pulse: "pulse";
+            }>;
+        }, z.core.$strict>>;
+        source: z.ZodString;
+        subject: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+        type: z.ZodString;
+        typeVersion: z.ZodNumber;
+        occurredAt: z.ZodString;
+        receivedAt: z.ZodString;
+    }, z.core.$strict>>;
+    source: z.ZodString;
+    subject: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    type: z.ZodString;
+    window: z.ZodObject<{
+        endAt: z.ZodString;
+        startAt: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strict>;
+export declare const PulseProcessorResultSchema: z.ZodObject<{
+    alreadyProcessed: z.ZodBoolean;
+    ok: z.ZodLiteral<true>;
+    signalId: z.ZodString;
+}, z.core.$strict>;
+export type PulseAggregate = z.infer<typeof PulseAggregateSchema>;
+export type PulseInput = z.infer<typeof PulseInputSchema>;
+export type PulseSubmission = z.infer<typeof PulseSubmissionSchema>;
+export type PulseTypeDefinition = z.infer<typeof PulseTypeDefinitionSchema>;
+export type PulseProcessorResult = z.infer<typeof PulseProcessorResultSchema>;
+export type RawPulse = z.infer<typeof RawPulseSchema>;
+export type RoutedLivePulse = z.infer<typeof RoutedLivePulseSchema>;
+export type SamplingContext = z.infer<typeof SamplingContextSchema>;
+export type SamplingPolicy = z.infer<typeof SamplingPolicySchema>;
+export type SdkConfiguration = z.infer<typeof SdkConfigurationSchema>;
+export type SdkPulseType = z.infer<typeof SdkPulseTypeSchema>;
+export type SignalTypeDefinition = z.infer<typeof SignalTypeDefinitionSchema>;
+export type LiveShardSnapshot = z.infer<typeof LiveShardSnapshotSchema>;
+export type MetricPulseTarget = z.infer<typeof MetricPulseTargetSchema>;
+export type MetricSnapshot = z.infer<typeof MetricSnapshotSchema>;
+export type RoutedMetricPulse = z.infer<typeof RoutedMetricPulseSchema>;

package/dist/contracts/payloadSchema.d.ts

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export declare const compilePayloadSchema: (value: Record<string, unknown>) => z.ZodType<Record<string, unknown>>;

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import type { PulseSubmission } from './contracts/index.js';
+import type { SdkConfigurationCache } from './configurationCache.js';
+export { CloudflareSdkConfigurationCache, MemorySdkConfigurationCache } from './configurationCache.js';
+export type { CachedSdkConfiguration, SdkConfigurationCache } from './configurationCache.js';
+export { CloudflareSamplingPolicyCache, MemorySamplingPolicyCache } from './cache.js';
+export type { CacheApiLike, SamplingPolicyCache } from './cache.js';
+export type SdkPulseInput = Omit<PulseSubmission, 'source' | 'sampling' | 'pulse'> & {
+    pulse: Omit<PulseSubmission['pulse'], 'id'> & {
+        id?: string;
+    };
+};
+export interface UnlimitedClientOptions {
+    apiToken: string;
+    baseUrl: string;
+    source: string;
+    cache?: SdkConfigurationCache;
+    fetch?: typeof fetch;
+    now?: () => Date;
+    randomUUID?: () => string;
+}
+export interface EmitResult {
+    accepted: boolean;
+    disabled?: boolean;
+    pulseId: string;
+    sampledOut: boolean;
+}
+export declare class UnlimitedClient {
+    private readonly apiToken;
+    private readonly baseUrl;
+    private readonly source;
+    private readonly cache;
+    private readonly fetcher;
+    private readonly now;
+    private readonly randomUUID;
+    private readonly cacheKey;
+    private loaded?;
+    private refreshing?;
+    constructor(options: UnlimitedClientOptions);
+    private install;
+    private refresh;
+    private configuration;
+    emit(input: SdkPulseInput): Promise<EmitResult>;
+}

package/dist/index.js

@@ -0,0 +1,656 @@
+// ../../libs/contracts/dist/index.js
+import { z as z2 } from "zod";
+
+// ../../libs/contracts/dist/payloadSchema.js
+import { z } from "zod";
+var compilePayloadSchema = (value) => {
+  const schema = value;
+  if (schema.type !== "object" || !schema.properties || !Array.isArray(schema.required)) {
+    throw new Error("PulseType needs an object payload schema with properties and required fields.");
+  }
+  const required = new Set(schema.required);
+  const fields = {};
+  for (const [name, field] of Object.entries(schema.properties)) {
+    let validator;
+    if (field.enum) {
+      if (field.enum.length === 0 || field.enum.some((item) => typeof item !== "string")) {
+        throw new Error(`Invalid enum for ${name}.`);
+      }
+      validator = z.enum(field.enum);
+    } else if (field.type === "string") {
+      let string = z.string();
+      if (field.minLength !== void 0)
+        string = string.min(field.minLength);
+      if (field.maxLength !== void 0)
+        string = string.max(field.maxLength);
+      if (field.format === "date-time") {
+        validator = string.refine((item) => Number.isFinite(Date.parse(item)), "Invalid date-time.");
+      } else if (field.format === void 0) {
+        validator = string;
+      } else {
+        throw new Error(`Unsupported string format for ${name}.`);
+      }
+    } else if (field.type === "number" || field.type === "integer") {
+      let number = field.type === "integer" ? z.number().int() : z.number();
+      if (field.minimum !== void 0)
+        number = number.min(field.minimum);
+      if (field.maximum !== void 0)
+        number = number.max(field.maximum);
+      validator = number;
+    } else if (field.type === "boolean") {
+      validator = z.boolean();
+    } else {
+      throw new Error(`Unsupported payload field ${name}.`);
+    }
+    fields[name] = required.has(name) ? validator : validator.optional();
+  }
+  for (const name of required) {
+    if (!fields[name])
+      throw new Error(`Required payload field ${name} is undefined.`);
+  }
+  const object = z.object(fields);
+  return schema.additionalProperties === false ? object.strict() : object.passthrough();
+};
+
+// ../../libs/contracts/dist/index.js
+var isoDateTime = z2.string().refine((value) => Number.isFinite(Date.parse(value)), "Expected an ISO date-time string.");
+var PulseSubjectSchema = z2.object({
+  id: z2.string().trim().min(1).max(200),
+  type: z2.string().trim().min(1).max(100)
+});
+var SamplingMethodSchema = z2.enum(["none", "pulse-hash-v1"]);
+var SamplingUnitSchema = z2.enum(["pulse", "member"]);
+var SamplingContextSchema = z2.object({
+  applied: z2.boolean(),
+  appliedKeepProbability: z2.number().min(0).max(1),
+  effectiveKeepProbability: z2.number().min(0).max(1),
+  ingressApplied: z2.boolean(),
+  ingressKeepProbability: z2.number().min(0).max(1),
+  ingressMethod: SamplingMethodSchema,
+  knownKeepProbability: z2.number().min(0).max(1).nullable(),
+  method: SamplingMethodSchema,
+  policyId: z2.string().trim().min(1).max(200).nullable(),
+  policyRevision: z2.number().int().nonnegative().nullable(),
+  unit: SamplingUnitSchema
+}).strict().superRefine((sampling, context) => {
+  if (!sampling.applied && sampling.appliedKeepProbability !== 1) {
+    context.addIssue({
+      code: "custom",
+      message: "appliedKeepProbability must be 1 when sampling was not applied.",
+      path: ["appliedKeepProbability"]
+    });
+  }
+  if (sampling.applied && sampling.method === "none") {
+    context.addIssue({
+      code: "custom",
+      message: "Sampling method cannot be none when sampling was applied.",
+      path: ["method"]
+    });
+  }
+  if (!sampling.applied && sampling.method !== "none") {
+    context.addIssue({
+      code: "custom",
+      message: "Sampling method must be none when SDK sampling was not applied.",
+      path: ["method"]
+    });
+  }
+  if (!sampling.ingressApplied && sampling.ingressKeepProbability !== 1) {
+    context.addIssue({
+      code: "custom",
+      message: "ingressKeepProbability must be 1 when ingress sampling was not applied.",
+      path: ["ingressKeepProbability"]
+    });
+  }
+  if (sampling.ingressApplied && sampling.ingressMethod === "none") {
+    context.addIssue({
+      code: "custom",
+      message: "Ingress sampling method cannot be none when ingress sampling was applied.",
+      path: ["ingressMethod"]
+    });
+  }
+  if (!sampling.ingressApplied && sampling.ingressMethod !== "none") {
+    context.addIssue({
+      code: "custom",
+      message: "Ingress sampling method must be none when ingress sampling was not applied.",
+      path: ["ingressMethod"]
+    });
+  }
+  if (sampling.policyId === null !== (sampling.policyRevision === null)) {
+    context.addIssue({
+      code: "custom",
+      message: "policyId and policyRevision must either both be set or both be null.",
+      path: ["policyId"]
+    });
+  }
+  const expected = sampling.appliedKeepProbability * sampling.ingressKeepProbability;
+  if (Math.abs(sampling.effectiveKeepProbability - expected) > 1e-12) {
+    context.addIssue({
+      code: "custom",
+      message: "effectiveKeepProbability must equal the product of applied sampling stages.",
+      path: ["effectiveKeepProbability"]
+    });
+  }
+});
+var NoSamplingContext = {
+  applied: false,
+  appliedKeepProbability: 1,
+  effectiveKeepProbability: 1,
+  ingressApplied: false,
+  ingressKeepProbability: 1,
+  ingressMethod: "none",
+  knownKeepProbability: null,
+  method: "none",
+  policyId: null,
+  policyRevision: null,
+  unit: "pulse"
+};
+var PulseInputSchema = z2.object({
+  data: z2.record(z2.string(), z2.unknown()).default({}),
+  eventId: z2.string().trim().min(1).max(200).optional(),
+  id: z2.string().trim().min(1).max(200),
+  organizationId: z2.string().trim().min(1).max(100),
+  occurredAt: isoDateTime.optional(),
+  sampling: SamplingContextSchema.default(NoSamplingContext),
+  source: z2.string().trim().min(1).max(100),
+  subject: PulseSubjectSchema.optional(),
+  type: z2.string().trim().min(1).max(100),
+  typeVersion: z2.number().int().positive()
+}).strict();
+var PulseSubmissionSchema = z2.object({
+  occurredAtMs: z2.number().int().min(0).max(864e13),
+  organizationId: z2.string().trim().min(1).max(100),
+  pulse: z2.object({
+    eventId: z2.string().trim().min(1).max(200).optional(),
+    id: z2.string().trim().min(1).max(200),
+    payload: z2.record(z2.string(), z2.unknown()).default({}),
+    subject: PulseSubjectSchema.optional(),
+    type: z2.string().trim().min(1).max(100),
+    version: z2.number().int().positive()
+  }).strict(),
+  sampling: SamplingContextSchema.default(NoSamplingContext),
+  source: z2.string().trim().min(1).max(100)
+}).strict();
+var RawPulseSchema = PulseInputSchema.extend({
+  occurredAt: isoDateTime,
+  receivedAt: isoDateTime
+});
+var PulseDeliverySchema = z2.enum(["live", "reliable"]);
+var PulseTypeDefinitionSchema = z2.object({
+  delivery: PulseDeliverySchema,
+  id: z2.string().trim().min(1).max(100),
+  payloadSchema: z2.record(z2.string(), z2.unknown()),
+  requiresExplicitId: z2.boolean().optional(),
+  sampling: z2.object({
+    keyField: z2.string().trim().min(1).max(200).nullable(),
+    unit: SamplingUnitSchema
+  }).strict().optional(),
+  samplingAllowed: z2.boolean(),
+  version: z2.number().int().positive()
+}).strict().superRefine((definition, context) => {
+  if (definition.samplingAllowed !== Boolean(definition.sampling)) {
+    context.addIssue({ code: "custom", path: ["sampling"], message: "Sampling selector must be present exactly when sampling is allowed." });
+  }
+  if (definition.sampling?.unit === "member" && !definition.sampling.keyField) {
+    context.addIssue({ code: "custom", path: ["sampling", "keyField"], message: "Member sampling requires keyField." });
+  }
+  if (definition.sampling?.unit === "pulse" && definition.sampling.keyField !== null) {
+    context.addIssue({ code: "custom", path: ["sampling", "keyField"], message: "Pulse sampling must not define keyField." });
+  }
+});
+var SignalReducerSchema = z2.enum(["presence", "distinct-per-window"]);
+var SignalTypeDefinitionSchema = z2.object({
+  id: z2.string().trim().min(1).max(100),
+  inputPulseTypes: z2.array(z2.object({
+    id: z2.string().trim().min(1).max(100),
+    version: z2.number().int().positive()
+  }).strict()).min(1),
+  dimensions: z2.array(z2.string().trim().min(1).max(100)).optional(),
+  partitionKey: z2.string().trim().min(1).max(200).optional(),
+  presence: z2.object({
+    immutableDimensions: z2.array(z2.string().trim().min(1).max(100)).optional(),
+    memberIdField: z2.string().trim().min(1).max(200),
+    startedAtField: z2.string().trim().min(1).max(200).optional(),
+    timeoutMs: z2.number().int().min(1e3).max(864e5)
+  }).strict().optional(),
+  reducer: SignalReducerSchema,
+  shardCount: z2.number().int().min(1).max(1024),
+  shardSchedule: z2.array(z2.object({
+    effectiveFrom: isoDateTime,
+    generation: z2.number().int().positive(),
+    shardCount: z2.number().int().min(1).max(65536)
+  }).strict()).optional(),
+  version: z2.number().int().positive(),
+  windowMs: z2.number().int().min(1e3).max(864e5).optional()
+}).strict().superRefine((definition, context) => {
+  if (definition.reducer === "presence" && !definition.presence) {
+    context.addIssue({ code: "custom", path: ["presence"], message: "Presence needs a timeout." });
+  }
+  if (definition.reducer === "distinct-per-window" && !definition.windowMs) {
+    context.addIssue({ code: "custom", path: ["windowMs"], message: "Windowed distinct needs a window." });
+  }
+  const schedule = definition.shardSchedule ?? [];
+  if (schedule.length > 0 && (!definition.partitionKey || !definition.dimensions?.length)) {
+    context.addIssue({ code: "custom", path: ["partitionKey"], message: "Scheduled routing needs partitionKey and dimensions." });
+  }
+  if (schedule.length > 0 && definition.reducer === "presence" && !definition.presence?.startedAtField) {
+    context.addIssue({ code: "custom", path: ["presence", "startedAtField"], message: "Scheduled presence needs a stable start time." });
+  }
+  if (definition.windowMs) {
+    for (let index = 0; index < schedule.length; index += 1) {
+      if (Date.parse(schedule[index].effectiveFrom) % definition.windowMs !== 0) {
+        context.addIssue({ code: "custom", path: ["shardSchedule", index], message: "Window generation must start on a window boundary." });
+      }
+    }
+  }
+  for (let index = 1; index < schedule.length; index += 1) {
+    if (Date.parse(schedule[index].effectiveFrom) <= Date.parse(schedule[index - 1].effectiveFrom) || schedule[index].generation <= schedule[index - 1].generation) {
+      context.addIssue({ code: "custom", path: ["shardSchedule", index], message: "Routing generations must increase in time and number." });
+    }
+  }
+});
+var MetricSignalRefSchema = z2.object({
+  signalId: z2.string().trim().min(1).max(500),
+  dimension: z2.string().trim().min(1).max(100)
+}).strict();
+var MetricPulseTargetSchema = z2.object({
+  generation: z2.number().int().positive(),
+  immutableDimensions: z2.array(z2.string().trim().min(1).max(100)).optional(),
+  kind: z2.enum(["presence", "distinct-per-window"]),
+  memberId: z2.string().trim().min(1).max(200),
+  organizationId: z2.string().trim().min(1).max(100),
+  ownerId: z2.string().trim().min(1).max(500),
+  refs: z2.array(MetricSignalRefSchema).min(1),
+  sessionStartedAt: isoDateTime,
+  shardCount: z2.number().int().min(1).max(65536),
+  shardIndex: z2.number().int().nonnegative(),
+  signalTypeId: z2.string().trim().min(1).max(100),
+  timeoutMs: z2.number().int().positive().optional(),
+  windowEndAt: isoDateTime.optional(),
+  windowStartAt: isoDateTime.optional()
+}).strict().superRefine((target, context) => {
+  if (target.shardIndex >= target.shardCount) {
+    context.addIssue({ code: "custom", path: ["shardIndex"], message: "Shard index exceeds shard count." });
+  }
+  if (target.kind === "presence" && !target.timeoutMs) {
+    context.addIssue({ code: "custom", path: ["timeoutMs"], message: "Presence needs a timeout." });
+  }
+  if (target.kind === "distinct-per-window" && (!target.windowStartAt || !target.windowEndAt)) {
+    context.addIssue({ code: "custom", path: ["windowStartAt"], message: "Distinct needs a window." });
+  }
+});
+var RoutedMetricPulseSchema = z2.object({
+  pulse: RawPulseSchema,
+  target: MetricPulseTargetSchema
+}).strict();
+var MetricSnapshotSchema = z2.object({
+  estimatedCount: z2.number().finite().nonnegative(),
+  generation: z2.number().int().positive(),
+  kind: z2.enum(["presence", "distinct-per-window"]),
+  observedAt: isoDateTime,
+  organizationId: z2.string().trim().min(1).max(100),
+  originId: z2.string().trim().min(1).max(200),
+  recovering: z2.boolean(),
+  revision: z2.number().int().nonnegative(),
+  sampledCount: z2.number().int().nonnegative(),
+  shardCount: z2.number().int().min(1).max(65536),
+  signalId: z2.string().trim().min(1).max(500),
+  signalTypeId: z2.string().trim().min(1).max(100),
+  windowEndAt: isoDateTime.optional(),
+  windowStartAt: isoDateTime.optional()
+}).strict().superRefine((snapshot, context) => {
+  if (snapshot.kind === "distinct-per-window" && (!snapshot.windowStartAt || !snapshot.windowEndAt)) {
+    context.addIssue({ code: "custom", path: ["windowStartAt"], message: "Distinct snapshot needs a window." });
+  }
+  if (snapshot.kind === "presence" && (snapshot.windowStartAt || snapshot.windowEndAt)) {
+    context.addIssue({ code: "custom", path: ["windowStartAt"], message: "Presence snapshot must not have a window." });
+  }
+});
+var SamplingPolicySchema = z2.object({
+  expiresAt: isoDateTime,
+  keyField: z2.string().trim().min(1).max(200).nullable(),
+  keepProbability: z2.number().min(0).max(1),
+  method: z2.literal("pulse-hash-v1"),
+  policyId: z2.string().trim().min(1).max(200),
+  pulseTypeId: z2.string().trim().min(1).max(100),
+  pulseTypeVersion: z2.number().int().positive(),
+  revision: z2.number().int().nonnegative(),
+  unit: SamplingUnitSchema
+}).strict().superRefine((policy, context) => {
+  if (policy.unit === "member" && !policy.keyField) {
+    context.addIssue({ code: "custom", message: "Member sampling requires keyField.", path: ["keyField"] });
+  }
+  if (policy.unit === "pulse" && policy.keyField !== null) {
+    context.addIssue({ code: "custom", message: "Pulse sampling cannot define keyField.", path: ["keyField"] });
+  }
+});
+var SdkPulseTypeSchema = z2.object({
+  definition: PulseTypeDefinitionSchema,
+  enabled: z2.boolean(),
+  samplingPolicy: SamplingPolicySchema.nullable()
+}).strict().superRefine((entry, context) => {
+  if (!entry.definition.samplingAllowed && entry.samplingPolicy !== null) {
+    context.addIssue({ code: "custom", path: ["samplingPolicy"], message: "Sampling is forbidden by PulseType." });
+  }
+  if (entry.samplingPolicy && (entry.samplingPolicy.pulseTypeId !== entry.definition.id || entry.samplingPolicy.pulseTypeVersion !== entry.definition.version)) {
+    context.addIssue({ code: "custom", path: ["samplingPolicy"], message: "Sampling policy targets a different PulseType." });
+  }
+});
+var SdkConfigurationSchema = z2.object({
+  expiresAt: isoDateTime,
+  pulseTypes: z2.array(SdkPulseTypeSchema),
+  revision: z2.number().int().nonnegative()
+}).strict();
+var LivePulseTargetSchema = z2.object({
+  generation: z2.number().int().positive(),
+  memberId: z2.string().trim().min(1).max(300),
+  organizationId: z2.string().trim().min(1).max(100),
+  reducer: SignalReducerSchema,
+  shardId: z2.string().trim().min(1).max(100),
+  signalId: z2.string().trim().min(1).max(500),
+  signalTypeId: z2.string().trim().min(1).max(100),
+  signalTypeVersion: z2.number().int().positive(),
+  timeoutMs: z2.number().int().min(1e3).max(864e5)
+}).strict();
+var RoutedLivePulseSchema = z2.object({
+  pulse: RawPulseSchema,
+  target: LivePulseTargetSchema
+}).strict();
+var LiveShardSnapshotSchema = z2.object({
+  activeCount: z2.number().int().nonnegative(),
+  estimatedActiveCount: z2.number().finite().nonnegative(),
+  observedAt: isoDateTime,
+  organizationId: z2.string().trim().min(1).max(100),
+  recovering: z2.boolean(),
+  revision: z2.number().int().nonnegative(),
+  shardId: z2.string().trim().min(1).max(100),
+  signalId: z2.string().trim().min(1).max(500),
+  signalTypeId: z2.string().trim().min(1).max(100)
+}).strict();
+var PulseAggregateSchema = z2.object({
+  aggregationKey: z2.string().min(1).max(600),
+  count: z2.number().int().positive().max(100),
+  createdAt: isoDateTime,
+  id: z2.string().trim().min(1).max(100),
+  organizationId: z2.string().trim().min(1).max(100),
+  pulses: z2.array(RawPulseSchema).min(1).max(100),
+  source: z2.string().trim().min(1).max(100),
+  subject: PulseSubjectSchema.optional(),
+  type: z2.string().trim().min(1).max(100),
+  window: z2.object({
+    endAt: isoDateTime,
+    startAt: isoDateTime
+  })
+}).strict().superRefine((aggregate, context) => {
+  if (aggregate.count !== aggregate.pulses.length) {
+    context.addIssue({
+      code: "custom",
+      message: "count must match pulses.length.",
+      path: ["count"]
+    });
+  }
+});
+var PulseProcessorResultSchema = z2.object({
+  alreadyProcessed: z2.boolean(),
+  ok: z2.literal(true),
+  signalId: z2.string().min(1)
+}).strict();
+
+// src/configurationCache.ts
+var MemorySdkConfigurationCache = class {
+  values = /* @__PURE__ */ new Map();
+  async get(key) {
+    return this.values.get(key);
+  }
+  async set(key, value) {
+    this.values.set(key, { configuration: SdkConfigurationSchema.parse(value.configuration), etag: value.etag });
+  }
+};
+var CloudflareSdkConfigurationCache = class {
+  constructor(cache, namespace = "https://sdk-config-cache.ultd.invalid") {
+    this.cache = cache;
+    this.namespace = namespace;
+  }
+  cache;
+  namespace;
+  request(key) {
+    return new Request(`${this.namespace}/${encodeURIComponent(key)}`);
+  }
+  async get(key) {
+    const response = await this.cache.match(this.request(key));
+    if (!response) return void 0;
+    const parsed = SdkConfigurationSchema.safeParse(await response.json());
+    return parsed.success ? { configuration: parsed.data, etag: response.headers.get("etag") } : void 0;
+  }
+  async set(key, value) {
+    const configuration = SdkConfigurationSchema.parse(value.configuration);
+    const remainingSeconds = Math.max(1, Math.floor((Date.parse(configuration.expiresAt) - Date.now()) / 1e3));
+    await this.cache.put(this.request(key), new Response(JSON.stringify(configuration), {
+      headers: {
+        // This is an internal Cache API entry under a token-derived key, not an HTTP response to the caller.
+        "cache-control": `public, max-age=${remainingSeconds}`,
+        "content-type": "application/json",
+        ...value.etag ? { etag: value.etag } : {}
+      }
+    }));
+  }
+};
+
+// src/cache.ts
+var MemorySamplingPolicyCache = class {
+  policies = /* @__PURE__ */ new Map();
+  async get(key) {
+    return this.policies.get(key);
+  }
+  async set(key, policy) {
+    this.policies.set(key, SamplingPolicySchema.parse(policy));
+  }
+};
+var CloudflareSamplingPolicyCache = class {
+  constructor(cache, namespace = "https://sampling-cache.ultd.invalid") {
+    this.cache = cache;
+    this.namespace = namespace;
+  }
+  cache;
+  namespace;
+  request(key) {
+    return new Request(`${this.namespace}/${encodeURIComponent(key)}`);
+  }
+  async get(key) {
+    const response = await this.cache.match(this.request(key));
+    if (!response) return void 0;
+    const parsed = SamplingPolicySchema.safeParse(await response.json());
+    return parsed.success ? parsed.data : void 0;
+  }
+  async set(key, policy) {
+    const parsed = SamplingPolicySchema.parse(policy);
+    const remainingSeconds = Math.max(1, Math.floor((Date.parse(parsed.expiresAt) - Date.now()) / 1e3));
+    await this.cache.put(this.request(key), new Response(JSON.stringify(parsed), {
+      headers: {
+        "cache-control": `max-age=${remainingSeconds}`,
+        "content-type": "application/json",
+        etag: `"${parsed.policyId}:${parsed.revision}"`
+      }
+    }));
+  }
+};
+
+// src/index.ts
+var typeKey = (type, version) => `${type}@${version}`;
+var selectedByHash = async (value, probability) => {
+  if (probability <= 0) return false;
+  if (probability >= 1) return true;
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return new DataView(digest).getUint32(0) / 4294967296 < probability;
+};
+var selectionValue = (input, policy, pulseId) => {
+  if (policy.unit === "pulse") return pulseId;
+  const value = policy.keyField === "pulse.id" ? pulseId : policy.keyField ? input.pulse.payload[policy.keyField] : void 0;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Sampling policy ${policy.policyId} requires string field ${policy.keyField}.`);
+  }
+  return value;
+};
+var configKey = async (baseUrl, apiToken) => {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${baseUrl}\0${apiToken}`));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+var UnlimitedClient = class {
+  apiToken;
+  baseUrl;
+  source;
+  cache;
+  fetcher;
+  now;
+  randomUUID;
+  cacheKey;
+  loaded;
+  refreshing;
+  constructor(options) {
+    if (!options.apiToken?.trim()) {
+      throw new Error("apiToken is required.");
+    }
+    if (!options.source?.trim()) {
+      throw new Error("source is required.");
+    }
+    this.apiToken = options.apiToken;
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.source = options.source;
+    this.cache = options.cache ?? new MemorySdkConfigurationCache();
+    this.fetcher = options.fetch ?? fetch;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    this.randomUUID = options.randomUUID ?? (() => crypto.randomUUID());
+    this.cacheKey = configKey(this.baseUrl, this.apiToken);
+  }
+  install(cached) {
+    const configuration = SdkConfigurationSchema.parse(cached.configuration);
+    if (Date.parse(configuration.expiresAt) <= this.now().getTime()) {
+      throw new Error("SDK configuration has expired.");
+    }
+    const types = /* @__PURE__ */ new Map();
+    for (const entry of configuration.pulseTypes) {
+      const key = typeKey(entry.definition.id, entry.definition.version);
+      if (types.has(key)) throw new Error(`Duplicate PulseType ${key} in SDK configuration.`);
+      types.set(key, { entry, validate: compilePayloadSchema(entry.definition.payloadSchema) });
+    }
+    return { cached: { configuration, etag: cached.etag }, types };
+  }
+  async refresh() {
+    const key = await this.cacheKey;
+    const cached = this.loaded?.cached ?? await this.cache.get(key).catch(() => void 0);
+    if (cached && Date.parse(cached.configuration.expiresAt) > this.now().getTime()) {
+      return this.install(cached);
+    }
+    const response = await this.fetcher(`${this.baseUrl}/v1/sdk-config`, {
+      headers: {
+        authorization: `Bearer ${this.apiToken}`,
+        ...cached?.etag ? { "if-none-match": cached.etag } : {}
+      }
+    });
+    let next;
+    if (response.status === 304) {
+      if (!cached) throw new Error("SDK configuration returned 304 without a cached body.");
+      const expiresAt = response.headers.get("x-ultd-config-expires-at");
+      if (!expiresAt || !Number.isFinite(Date.parse(expiresAt))) {
+        throw new Error("SDK configuration returned 304 without a valid expiry.");
+      }
+      next = {
+        configuration: {
+          ...cached.configuration,
+          expiresAt,
+          pulseTypes: cached.configuration.pulseTypes.map((entry) => ({
+            ...entry,
+            samplingPolicy: entry.samplingPolicy && { ...entry.samplingPolicy, expiresAt }
+          }))
+        },
+        etag: cached.etag
+      };
+    } else {
+      if (!response.ok) throw new Error(`SDK configuration request failed with ${response.status}.`);
+      next = { configuration: SdkConfigurationSchema.parse(await response.json()), etag: response.headers.get("etag") };
+    }
+    const loaded = this.install(next);
+    await this.cache.set(key, loaded.cached).catch(() => void 0);
+    return loaded;
+  }
+  async configuration() {
+    if (this.loaded && Date.parse(this.loaded.cached.configuration.expiresAt) > this.now().getTime()) {
+      return this.loaded;
+    }
+    this.refreshing ??= this.refresh().then((loaded) => {
+      this.loaded = loaded;
+      return loaded;
+    }).finally(() => {
+      this.refreshing = void 0;
+    });
+    return this.refreshing;
+  }
+  async emit(input) {
+    const loaded = await this.configuration();
+    const type = loaded.types.get(typeKey(input.pulse.type, input.pulse.version));
+    if (!type) throw new Error(`Unknown PulseType ${input.pulse.type}@${input.pulse.version}.`);
+    if (type.entry.definition.requiresExplicitId && !input.pulse.id) {
+      throw new Error(`PulseType ${input.pulse.type}@${input.pulse.version} requires an explicit stable pulse.id.`);
+    }
+    const id = input.pulse.id ?? this.randomUUID();
+    const validated = PulseSubmissionSchema.parse({
+      ...input,
+      pulse: { ...input.pulse, id },
+      sampling: NoSamplingContext,
+      source: this.source
+    });
+    const payload = type.validate.parse(validated.pulse.payload);
+    if (!type.entry.enabled) {
+      return { accepted: false, disabled: true, pulseId: id, sampledOut: false };
+    }
+    const policy = type.entry.samplingPolicy;
+    let sampling = NoSamplingContext;
+    if (policy) {
+      sampling = {
+        applied: policy.keepProbability < 1,
+        appliedKeepProbability: policy.keepProbability,
+        effectiveKeepProbability: policy.keepProbability,
+        ingressApplied: false,
+        ingressKeepProbability: 1,
+        ingressMethod: "none",
+        knownKeepProbability: policy.keepProbability,
+        method: policy.keepProbability < 1 ? policy.method : "none",
+        policyId: policy.policyId,
+        policyRevision: policy.revision,
+        unit: policy.unit
+      };
+      const selected = await selectedByHash(
+        `sdk:${policy.policyId}:${selectionValue(input, policy, id)}`,
+        policy.keepProbability
+      );
+      if (!selected) return { accepted: false, pulseId: id, sampledOut: true };
+    }
+    const submission = PulseSubmissionSchema.parse({
+      ...validated,
+      pulse: { ...validated.pulse, payload },
+      sampling
+    });
+    const response = await this.fetcher(`${this.baseUrl}/v1/pulses`, {
+      body: JSON.stringify(submission),
+      headers: {
+        authorization: `Bearer ${this.apiToken}`,
+        "content-type": "application/json"
+      },
+      method: "POST"
+    });
+    if (!response.ok) throw new Error(`Pulse request failed with ${response.status}.`);
+    const body = await response.json();
+    return {
+      accepted: body.accepted !== false,
+      ...body.disabled === true ? { disabled: true } : {},
+      pulseId: id,
+      sampledOut: body.sampledOut === true
+    };
+  }
+};
+export {
+  CloudflareSamplingPolicyCache,
+  CloudflareSdkConfigurationCache,
+  MemorySamplingPolicyCache,
+  MemorySdkConfigurationCache,
+  UnlimitedClient
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@ultdai/pulse",
+  "version": "0.1.0",
+  "type": "module",
+  "files": ["dist", "README.md"],
+  "publishConfig": { "access": "public" },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json --emitDeclarationOnly && node scripts/bundle.mjs",
+    "prepack": "pnpm --dir ../../libs/contracts run build && pnpm run build",
+    "test": "vitest run test --exclude 'dist/**'",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@ultdai/contracts": "workspace:*",
+    "esbuild": "0.28.1",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  }
+}