@ultdai/pulse 0.2.0 → 0.3.1

package/README.md

@@ -7,49 +7,54 @@ npm install @ultdai/pulse
 ```
 
 ```ts
-import {
-  CloudflareSdkConfigurationCache,
-  CloudflareSessionDecisionCache,
-  UnlimitedClient,
-} from '@ultdai/pulse'
+import { CloudflareSdkConfigurationCache, UnlimitedClient } from '@ultdai/pulse'
 
-export interface Env { ULTD_API_TOKEN: string }
+interface Env {
+  ULTD_API_TOKEN: string
+  ULTD_API_URL: string
+  ULTD_ORGANIZATION_ID: string
+}
 
 let client: UnlimitedClient | undefined
 
 export default {
   async fetch(request: Request, env: Env, context: ExecutionContext) {
-    const session = getPlaybackSession(request) // stabilní ID a čas vzniku v Unixových milisekundách
     client ??= new UnlimitedClient({
       apiToken: env.ULTD_API_TOKEN,
-      baseUrl: 'https://api.ultd.tivio.studio',
+      baseUrl: env.ULTD_API_URL,
       cache: new CloudflareSdkConfigurationCache(caches.default),
-      sessionCache: new CloudflareSessionDecisionCache(caches.default),
-      source: 'stream-worker',
+      source: 'my-server',
     })
-    context.waitUntil(client.emit({
-      occurredAtMs: Date.now(),
-      organizationId: 'tivio',
-      pulse: {
-        type: 'playback.session.playing',
-        version: 1,
-        id: session.id,
-        payload: {
-          sessionStartedAtMs: session.startedAtMs,
-          videoId: session.videoId,
-          ...(session.channelId ? { channelId: session.channelId } : {}),
+
+    // Inicializace načte aktuální povolené typy a jejich pravidla. Další
+    // volání používají platnou cache; po expiraci se katalog obnoví.
+    context.waitUntil((async () => {
+      await client.initialize('') // výběr organizace je rezervovaný pro budoucí katalog
+      await client.emit({
+        organizationId: env.ULTD_ORGANIZATION_ID,
+        occurredAtMs: Date.now(),
+        pulse: {
+          type: 'your.configured.pulse-type',
+          version: 1,
+          id: crypto.randomUUID(),
+          payload: { value: 1 },
         },
-      },
-    }).catch((error) => console.error('ULTD pulse failed', error)))
+      })
+    })().catch((error) => console.error('ULTD pulse failed', error)))
+
     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.
+Ukázkový PulseType výše je jen zástupný název. Skutečný název, verzi, identitu a pole payloadu určuje vaše konfigurace v ULTD. Opakované pulsy, které patří ke stejné sledované entitě, musí používat stabilní `pulse.id`; jednorázová událost potřebuje ID stabilní při opakovaném odeslání.
+
+`apiToken` 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.
+
+`await client.initialize(token)` načte povolené PulseTypes, jejich schémata a pravidla měření z autorizovaného ULTD API nebo z dosud platné sdílené cache. Argument `token` je rezervovaný pro budoucí výběr organizace a jejího katalogu; v tomto POC se nepoužívá a smí být `''`. Není to API klíč ani náhrada za `apiToken`. Samotný konstruktor nemůže čekat na síť. Pokud inicializaci vynecháte, `emit()` konfiguraci načte před prvním pulsem. Neznámý typ nebo nevalidní `pulse.payload` SDK odmítne lokálně. Vypnutý nebo nevzorkovaný puls neodešle. 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 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 `sessionStartedAtMs` jsou Unixové časy v milisekundách. 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.
+Pro opakované pulsy může konfigurace definovat lifecycle s úvodním a průběžným PulseTypem. SDK při prvním volání odešle úvodní puls, uloží rozhodnutí o dalším měření a dodržuje interval z konfigurace. `CloudflareSessionDecisionCache(caches.default)` lze předat jako `sessionCache`, aby se toto rozhodnutí sdílelo mezi instancemi Workeru; bez něj se používá paměť instance. Cache je pouze optimalizace a její ztráta nezakládá novou logickou entitu.
 
-U `playback.session.playing@1` SDK při prvním volání pro session odešle idempotentní `playback.session.started@1`. API vrátí rozhodnutí, zda se session dále měří. Vybraná session pak odešle heartbeat nejdříve po 60 sekundách nebo při změně videa; ostatní volání skončí lokálně. Po ztrátě cache SDK zopakuje start se stejným ID a obnoví původní rozhodnutí. Pevné ID session a čas začátku musí dodávat producent. API a Durable Object opakovaný start rozpoznají; cache je pouze optimalizace.
+SDK obsahuje obecné 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á. SDK neobsahuje zákaznické PulseTypes. Samotné zveřejnění SDK neposkytuje oprávnění k API.
 
-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.
+Dnešní POC má na backendu jeden technický API klíč a jeden katalog definic. Rozdělení katalogu podle organizace je další serverový krok; rozhraní SDK už s jejím tokenem při inicializaci počítá.

package/dist/contracts/index.d.ts

@@ -163,6 +163,7 @@ export declare const PulseTypeDefinitionSchema: z.ZodObject<{
             start: "start";
         }>;
         intervalMs: z.ZodOptional<z.ZodNumber>;
+        reportOnChangeFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
     payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     requiresExplicitId: z.ZodOptional<z.ZodBoolean>;
@@ -177,11 +178,37 @@ export declare const PulseTypeDefinitionSchema: z.ZodObject<{
     version: z.ZodNumber;
 }, z.core.$strict>;
 export declare const SignalReducerSchema: z.ZodEnum<{
+    "additive-window": "additive-window";
     "distinct-per-window": "distinct-per-window";
     lifecycle: "lifecycle";
     presence: "presence";
 }>;
 export declare const SignalTypeDefinitionSchema: z.ZodObject<{
+    additive: z.ZodOptional<z.ZodObject<{
+        baseScopeFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cohortAtField: z.ZodString;
+        dedupeFields: z.ZodArray<z.ZodString>;
+        dimensionSets: z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            fields: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        latenessMs: z.ZodNumber;
+        metricRules: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            op: z.ZodEnum<{
+                count: "count";
+                sum: "sum";
+            }>;
+            unitField: z.ZodOptional<z.ZodString>;
+            valueField: z.ZodOptional<z.ZodString>;
+            when: z.ZodOptional<z.ZodObject<{
+                field: z.ZodString;
+                equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        primaryMetric: z.ZodString;
+        stableScopeField: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     inputPulseTypes: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -203,6 +230,7 @@ export declare const SignalTypeDefinitionSchema: z.ZodObject<{
         timeoutMs: z.ZodNumber;
     }, z.core.$strict>>;
     reducer: z.ZodEnum<{
+        "additive-window": "additive-window";
         "distinct-per-window": "distinct-per-window";
         lifecycle: "lifecycle";
         presence: "presence";
@@ -229,6 +257,7 @@ export declare const MetricPulseTargetSchema: z.ZodObject<{
     refs: z.ZodArray<z.ZodObject<{
         signalId: z.ZodString;
         dimension: z.ZodString;
+        scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>>;
     sessionStartedAt: z.ZodString;
     shardCount: z.ZodNumber;
@@ -289,6 +318,7 @@ export declare const RoutedMetricPulseSchema: z.ZodObject<{
         refs: z.ZodArray<z.ZodObject<{
             signalId: z.ZodString;
             dimension: z.ZodString;
+            scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, z.core.$strict>>;
         sessionStartedAt: z.ZodString;
         shardCount: z.ZodNumber;
@@ -299,6 +329,86 @@ export declare const RoutedMetricPulseSchema: z.ZodObject<{
         windowStartAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+/** A pulse carries a bounded vector of exact, non-sampled metric additions. */
+export declare const AdditivePulseTargetSchema: z.ZodObject<{
+    dedupeKey: z.ZodString;
+    generation: z.ZodNumber;
+    latenessMs: z.ZodNumber;
+    metrics: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    organizationId: z.ZodString;
+    ownerId: z.ZodString;
+    primaryMetric: z.ZodString;
+    refs: z.ZodArray<z.ZodObject<{
+        signalId: z.ZodString;
+        dimension: z.ZodString;
+        scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
+    shardCount: z.ZodNumber;
+    shardIndex: z.ZodNumber;
+    signalTypeId: z.ZodString;
+    stableScopeKey: z.ZodOptional<z.ZodString>;
+    windowEndAt: z.ZodString;
+    windowStartAt: z.ZodString;
+}, z.core.$strict>;
+export declare const RoutedAdditivePulseSchema: 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<{
+        dedupeKey: z.ZodString;
+        generation: z.ZodNumber;
+        latenessMs: z.ZodNumber;
+        metrics: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        organizationId: z.ZodString;
+        ownerId: z.ZodString;
+        primaryMetric: z.ZodString;
+        refs: z.ZodArray<z.ZodObject<{
+            signalId: z.ZodString;
+            dimension: z.ZodString;
+            scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strict>>;
+        shardCount: z.ZodNumber;
+        shardIndex: z.ZodNumber;
+        signalTypeId: z.ZodString;
+        stableScopeKey: z.ZodOptional<z.ZodString>;
+        windowEndAt: z.ZodString;
+        windowStartAt: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
 export declare const LifecyclePulseTargetSchema: z.ZodObject<{
     generation: z.ZodNumber;
     groupId: z.ZodString;
@@ -312,6 +422,7 @@ export declare const LifecyclePulseTargetSchema: z.ZodObject<{
     refs: z.ZodArray<z.ZodObject<{
         signalId: z.ZodString;
         dimension: z.ZodString;
+        scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>>;
     scopeId: z.ZodString;
     sessionStartedAt: z.ZodString;
@@ -372,6 +483,7 @@ export declare const RoutedLifecyclePulseSchema: z.ZodObject<{
         refs: z.ZodArray<z.ZodObject<{
             signalId: z.ZodString;
             dimension: z.ZodString;
+            scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         }, z.core.$strict>>;
         scopeId: z.ZodString;
         sessionStartedAt: z.ZodString;
@@ -393,15 +505,20 @@ export declare const MetricSnapshotSchema: z.ZodObject<{
     varianceEstimate: z.ZodOptional<z.ZodNumber>;
     generation: z.ZodNumber;
     kind: z.ZodEnum<{
+        "additive-window": "additive-window";
         "distinct-per-window": "distinct-per-window";
         presence: "presence";
     }>;
+    latenessMs: z.ZodOptional<z.ZodNumber>;
+    metrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
     observedAt: z.ZodString;
     organizationId: z.ZodString;
     originId: z.ZodString;
     recovering: z.ZodBoolean;
     revision: z.ZodNumber;
     sampledCount: z.ZodNumber;
+    scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    scopeKind: z.ZodOptional<z.ZodString>;
     shardCount: z.ZodNumber;
     signalId: z.ZodString;
     signalTypeId: z.ZodString;
@@ -436,6 +553,7 @@ export declare const SdkPulseTypeSchema: z.ZodObject<{
                 start: "start";
             }>;
             intervalMs: z.ZodOptional<z.ZodNumber>;
+            reportOnChangeFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
         payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         requiresExplicitId: z.ZodOptional<z.ZodBoolean>;
@@ -481,6 +599,7 @@ export declare const SdkConfigurationSchema: z.ZodObject<{
                     start: "start";
                 }>;
                 intervalMs: z.ZodOptional<z.ZodNumber>;
+                reportOnChangeFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>>;
             payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
             requiresExplicitId: z.ZodOptional<z.ZodBoolean>;
@@ -517,6 +636,7 @@ export declare const LivePulseTargetSchema: z.ZodObject<{
     memberId: z.ZodString;
     organizationId: z.ZodString;
     reducer: z.ZodEnum<{
+        "additive-window": "additive-window";
         "distinct-per-window": "distinct-per-window";
         lifecycle: "lifecycle";
         presence: "presence";
@@ -570,6 +690,7 @@ export declare const RoutedLivePulseSchema: z.ZodObject<{
         memberId: z.ZodString;
         organizationId: z.ZodString;
         reducer: z.ZodEnum<{
+            "additive-window": "additive-window";
             "distinct-per-window": "distinct-per-window";
             lifecycle: "lifecycle";
             presence: "presence";
@@ -667,6 +788,8 @@ 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>;
+export type RoutedAdditivePulse = z.infer<typeof RoutedAdditivePulseSchema>;
+export type AdditivePulseTarget = z.infer<typeof AdditivePulseTargetSchema>;
 export type RoutedLifecyclePulse = z.infer<typeof RoutedLifecyclePulseSchema>;
 export type LifecyclePulseTarget = z.infer<typeof LifecyclePulseTargetSchema>;
 export type LifecycleDecision = z.infer<typeof LifecycleDecisionSchema>;

package/dist/index.d.ts

@@ -49,6 +49,11 @@ export declare class UnlimitedClient {
     private install;
     private refresh;
     private configuration;
+    /** Load the authorized, versioned PulseType catalog before producing pulses.
+     * The organization token is reserved for future catalog scoping and currently
+     * has no effect, including when it is an empty string. API authentication
+     * continues to use the apiToken supplied in the constructor. */
+    initialize(_organizationToken: string): Promise<void>;
     private decisionKey;
     private getDecision;
     private putDecision;

package/dist/index.js

@@ -11,22 +11,29 @@ var compilePayloadSchema = (value) => {
   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 validator2;
+    if (field.pattern !== void 0 && field.type !== "string") {
+      throw new Error(`Pattern is only supported for string field ${name}.`);
+    }
+    if (field.type === "string" || field.type === void 0 && field.enum?.every((item) => typeof item === "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.pattern !== void 0) {
+        let pattern;
+        try {
+          pattern = new RegExp(field.pattern);
+        } catch {
+          throw new Error(`Invalid pattern for ${name}.`);
+        }
+        string = string.regex(pattern);
+      }
       if (field.format === "date-time") {
-        validator = string.refine((item) => Number.isFinite(Date.parse(item)), "Invalid date-time.");
+        validator2 = string.refine((item) => Number.isFinite(Date.parse(item)), "Invalid date-time.");
       } else if (field.format === void 0) {
-        validator = string;
+        validator2 = string;
       } else {
         throw new Error(`Unsupported string format for ${name}.`);
       }
@@ -36,20 +43,46 @@ var compilePayloadSchema = (value) => {
         number = number.min(field.minimum);
       if (field.maximum !== void 0)
         number = number.max(field.maximum);
-      validator = number;
+      validator2 = number;
     } else if (field.type === "boolean") {
-      validator = z.boolean();
+      validator2 = z.boolean();
     } else {
       throw new Error(`Unsupported payload field ${name}.`);
     }
-    fields[name] = required.has(name) ? validator : validator.optional();
+    if (field.enum !== void 0) {
+      const enumType = field.type === "number" || field.type === "integer" ? "number" : "string";
+      if (field.enum.length === 0 || field.enum.some((item) => typeof item !== enumType)) {
+        throw new Error(`Invalid enum for ${name}.`);
+      }
+      const allowed = new Set(field.enum);
+      validator2 = validator2.refine((item) => allowed.has(item), "Invalid enum value.");
+    }
+    fields[name] = required.has(name) ? validator2 : validator2.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();
+  const validator = schema.additionalProperties === false ? object.strict() : object.passthrough();
+  if (!schema.dependentRequired)
+    return validator;
+  for (const [field, dependents] of Object.entries(schema.dependentRequired)) {
+    if (!fields[field] || !Array.isArray(dependents) || dependents.some((dependent) => !fields[dependent])) {
+      throw new Error(`Invalid dependentRequired for ${field}.`);
+    }
+  }
+  return validator.superRefine((payload, context) => {
+    for (const [field, dependents] of Object.entries(schema.dependentRequired ?? {})) {
+      if (payload[field] === void 0)
+        continue;
+      for (const dependent of dependents) {
+        if (payload[dependent] === void 0) {
+          context.addIssue({ code: "custom", path: [dependent], message: `${dependent} is required with ${field}.` });
+        }
+      }
+    }
+  });
 };
 
 // ../../libs/contracts/dist/index.js
@@ -181,7 +214,8 @@ var PulseTypeDefinitionSchema = z2.object({
   lifecycle: z2.object({
     groupId: z2.string().trim().min(1).max(100),
     phase: z2.enum(["start", "observe"]),
-    intervalMs: z2.number().int().min(1e3).max(864e5).optional()
+    intervalMs: z2.number().int().min(1e3).max(864e5).optional(),
+    reportOnChangeFields: z2.array(z2.string().trim().min(1).max(200)).max(8).optional()
   }).strict().optional(),
   payloadSchema: z2.record(z2.string(), z2.unknown()),
   requiresExplicitId: z2.boolean().optional(),
@@ -204,9 +238,47 @@ var PulseTypeDefinitionSchema = z2.object({
   if (definition.lifecycle && (definition.samplingAllowed || !definition.requiresExplicitId || definition.delivery !== "live" || definition.lifecycle.phase === "observe" !== Boolean(definition.lifecycle.intervalMs))) {
     context.addIssue({ code: "custom", path: ["lifecycle"], message: "Lifecycle pulses need explicit IDs, live delivery, and an interval only for observations." });
   }
+  if (definition.lifecycle?.reportOnChangeFields) {
+    const fields = definition.lifecycle.reportOnChangeFields;
+    if (definition.lifecycle.phase !== "observe" || new Set(fields).size !== fields.length) {
+      context.addIssue({
+        code: "custom",
+        path: ["lifecycle", "reportOnChangeFields"],
+        message: "Change-trigger fields must be unique and belong to an observation PulseType."
+      });
+    }
+  }
+});
+var SignalReducerSchema = z2.enum(["presence", "distinct-per-window", "lifecycle", "additive-window"]);
+var MetricNameSchema = z2.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/).max(64);
+var AdditiveMetricRuleSchema = z2.object({
+  name: MetricNameSchema,
+  op: z2.enum(["count", "sum"]),
+  unitField: z2.string().trim().min(1).max(200).optional(),
+  valueField: z2.string().trim().min(1).max(200).optional(),
+  when: z2.object({
+    field: z2.string().trim().min(1).max(200),
+    equals: z2.union([z2.string(), z2.number().finite(), z2.boolean()])
+  }).strict().optional()
+}).strict().superRefine((rule, context) => {
+  if (rule.op === "sum" !== Boolean(rule.valueField)) {
+    context.addIssue({ code: "custom", path: ["valueField"], message: "Sum needs valueField; count must not have one." });
+  }
 });
-var SignalReducerSchema = z2.enum(["presence", "distinct-per-window", "lifecycle"]);
 var SignalTypeDefinitionSchema = z2.object({
+  additive: z2.object({
+    baseScopeFields: z2.array(z2.string().trim().min(1).max(100)).max(4).optional(),
+    cohortAtField: z2.string().trim().min(1).max(200),
+    dedupeFields: z2.array(z2.string().trim().min(1).max(200)).min(1).max(4),
+    dimensionSets: z2.array(z2.object({
+      kind: z2.string().trim().min(1).max(100),
+      fields: z2.array(z2.string().trim().min(1).max(100)).max(4)
+    }).strict()).min(1).max(16),
+    latenessMs: z2.number().int().min(0).max(36e5),
+    metricRules: z2.array(AdditiveMetricRuleSchema).min(1).max(32),
+    primaryMetric: MetricNameSchema,
+    stableScopeField: z2.string().trim().min(1).max(200).optional()
+  }).strict().optional(),
   id: z2.string().trim().min(1).max(100),
   inputPulseTypes: z2.array(z2.object({
     id: z2.string().trim().min(1).max(100),
@@ -246,8 +318,26 @@ var SignalTypeDefinitionSchema = z2.object({
   if (definition.reducer === "lifecycle" && (!definition.lifecycle || !definition.partitionKey || !definition.dimensions?.length)) {
     context.addIssue({ code: "custom", path: ["lifecycle"], message: "Lifecycle needs a configuration, partition key and dimensions." });
   }
+  if (definition.reducer === "additive-window") {
+    const additive = definition.additive;
+    if (!additive || !definition.windowMs || !definition.partitionKey) {
+      context.addIssue({ code: "custom", path: ["additive"], message: "Additive window needs metrics, windowMs and partitionKey." });
+    } else {
+      const names = additive.metricRules.map((rule) => rule.name);
+      if (new Set(names).size !== names.length || !names.includes(additive.primaryMetric)) {
+        context.addIssue({ code: "custom", path: ["additive", "metricRules"], message: "Metric names must be unique and include the primary metric." });
+      }
+      const kinds = additive.dimensionSets.map((set) => set.kind);
+      const sets = additive.dimensionSets.map((set) => JSON.stringify(set.fields));
+      if (new Set(sets).size !== sets.length || new Set(kinds).size !== kinds.length) {
+        context.addIssue({ code: "custom", path: ["additive", "dimensionSets"], message: "Dimension sets and kinds must be unique." });
+      }
+    }
+  } else if (definition.additive) {
+    context.addIssue({ code: "custom", path: ["additive"], message: "Only additive-window signals may define additive metrics." });
+  }
   const schedule = definition.shardSchedule ?? [];
-  if (schedule.length > 0 && (!definition.partitionKey || !definition.dimensions?.length)) {
+  if (schedule.length > 0 && (!definition.partitionKey || !definition.dimensions?.length && !definition.additive?.dimensionSets.length)) {
     context.addIssue({ code: "custom", path: ["partitionKey"], message: "Scheduled routing needs partitionKey and dimensions." });
   }
   if (schedule.length > 0 && definition.reducer === "presence" && !definition.presence?.startedAtField) {
@@ -269,7 +359,8 @@ var SignalTypeDefinitionSchema = z2.object({
 });
 var MetricSignalRefSchema = z2.object({
   signalId: z2.string().trim().min(1).max(500),
-  dimension: z2.string().trim().min(1).max(100)
+  dimension: z2.string().trim().min(1).max(100),
+  scope: z2.record(z2.string().trim().min(1).max(100), z2.string().trim().min(1).max(200)).optional()
 }).strict();
 var MetricPulseTargetSchema = z2.object({
   generation: z2.number().int().positive(),
@@ -301,6 +392,33 @@ var RoutedMetricPulseSchema = z2.object({
   pulse: RawPulseSchema,
   target: MetricPulseTargetSchema
 }).strict();
+var AdditivePulseTargetSchema = z2.object({
+  dedupeKey: z2.string().trim().min(1).max(500),
+  generation: z2.number().int().positive(),
+  latenessMs: z2.number().int().min(0).max(36e5),
+  metrics: z2.record(MetricNameSchema, z2.number().int().safe().nonnegative()),
+  organizationId: z2.string().trim().min(1).max(100),
+  ownerId: z2.string().trim().min(1).max(500),
+  primaryMetric: MetricNameSchema,
+  refs: z2.array(MetricSignalRefSchema).min(1).max(16),
+  shardCount: z2.number().int().min(1).max(65536),
+  shardIndex: z2.number().int().nonnegative(),
+  signalTypeId: z2.string().trim().min(1).max(100),
+  stableScopeKey: z2.string().trim().min(1).max(500).optional(),
+  windowEndAt: isoDateTime,
+  windowStartAt: isoDateTime
+}).strict().superRefine((target, context) => {
+  if (target.shardIndex >= target.shardCount || Date.parse(target.windowStartAt) >= Date.parse(target.windowEndAt)) {
+    context.addIssue({ code: "custom", path: ["shardIndex"], message: "Invalid additive shard or window." });
+  }
+  if (!Object.hasOwn(target.metrics, target.primaryMetric)) {
+    context.addIssue({ code: "custom", path: ["metrics"], message: "Additive metrics must include the primary metric." });
+  }
+  if (new Set(target.refs.map((ref) => ref.signalId)).size !== target.refs.length) {
+    context.addIssue({ code: "custom", path: ["refs"], message: "Additive signal references must be unique." });
+  }
+});
+var RoutedAdditivePulseSchema = z2.object({ pulse: RawPulseSchema, target: AdditivePulseTargetSchema }).strict();
 var LifecyclePulseTargetSchema = z2.object({
   generation: z2.number().int().positive(),
   groupId: z2.string().trim().min(1).max(100),
@@ -335,22 +453,38 @@ var MetricSnapshotSchema = z2.object({
   estimatedCount: z2.number().finite().nonnegative(),
   varianceEstimate: z2.number().finite().nonnegative().optional(),
   generation: z2.number().int().positive(),
-  kind: z2.enum(["presence", "distinct-per-window"]),
+  kind: z2.enum(["presence", "distinct-per-window", "additive-window"]),
+  latenessMs: z2.number().int().min(0).max(36e5).optional(),
+  metrics: z2.record(MetricNameSchema, z2.number().int().safe().nonnegative()).optional(),
   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(),
+  scope: z2.record(z2.string().trim().min(1).max(100), z2.string().trim().min(1).max(200)).optional(),
+  scopeKind: z2.string().trim().min(1).max(100).optional(),
   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)) {
+  if ((snapshot.kind === "distinct-per-window" || snapshot.kind === "additive-window") && (!snapshot.windowStartAt || !snapshot.windowEndAt)) {
     context.addIssue({ code: "custom", path: ["windowStartAt"], message: "Distinct snapshot needs a window." });
   }
+  if (snapshot.kind === "additive-window" && !snapshot.metrics) {
+    context.addIssue({ code: "custom", path: ["metrics"], message: "Additive snapshot needs metrics." });
+  }
+  if (snapshot.kind === "additive-window" && snapshot.latenessMs === void 0) {
+    context.addIssue({ code: "custom", path: ["latenessMs"], message: "Additive snapshot needs its lateness bound." });
+  }
+  if (snapshot.kind === "additive-window" && (!snapshot.scope || !snapshot.scopeKind)) {
+    context.addIssue({ code: "custom", path: ["scope"], message: "Additive snapshot needs a structured scope." });
+  }
+  if (snapshot.kind !== "additive-window" && snapshot.metrics) {
+    context.addIssue({ code: "custom", path: ["metrics"], message: "Only additive snapshots carry metrics." });
+  }
   if (snapshot.kind === "presence" && (snapshot.windowStartAt || snapshot.windowEndAt)) {
     context.addIssue({ code: "custom", path: ["windowStartAt"], message: "Presence snapshot must not have a window." });
   }
@@ -585,6 +719,12 @@ 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 reportedChangeKey = async (fields, payload) => {
+  if (!fields?.length) return void 0;
+  const values = fields.map((field) => [field, Object.hasOwn(payload, field), payload[field]]);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(values)));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
 var UnlimitedClient = class {
   apiToken;
   baseUrl;
@@ -678,6 +818,13 @@ var UnlimitedClient = class {
     });
     return this.refreshing;
   }
+  /** Load the authorized, versioned PulseType catalog before producing pulses.
+   * The organization token is reserved for future catalog scoping and currently
+   * has no effect, including when it is an empty string. API authentication
+   * continues to use the apiToken supplied in the constructor. */
+  async initialize(_organizationToken) {
+    await this.configuration();
+  }
   async decisionKey(groupId, organizationId, sessionId) {
     const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(
       `${await this.cacheKey}\0${groupId}\0${organizationId}\0${sessionId}`
@@ -719,6 +866,8 @@ var UnlimitedClient = class {
       return { accepted: false, disabled: true, pulseId: id, sampledOut: false };
     }
     const lifecycle = type.entry.definition.lifecycle;
+    const observation = lifecycle?.phase === "start" ? [...loaded.types.values()].find((candidate) => candidate.entry.definition.lifecycle?.groupId === lifecycle.groupId && candidate.entry.definition.lifecycle.phase === "observe") : type;
+    const changeKey = lifecycle ? await reportedChangeKey(observation?.entry.definition.lifecycle?.reportOnChangeFields, payload) : void 0;
     const decisionKey = lifecycle ? await this.decisionKey(lifecycle.groupId, input.organizationId, id) : void 0;
     if (lifecycle?.phase === "observe" && decisionKey) {
       const decision = await this.getDecision(decisionKey);
@@ -733,7 +882,7 @@ var UnlimitedClient = class {
       if (decision && !decision.selected) {
         return { accepted: false, pulseId: id, sampledOut: true, selected: false, probability: decision.probability };
       }
-      if (decision && this.now().getTime() < decision.nextHeartbeatAtMs && decision.lastVideoId === payload.videoId) {
+      if (decision && this.now().getTime() < decision.nextHeartbeatAtMs && decision.lastReportedChangeKey === changeKey) {
         return {
           accepted: false,
           pulseId: id,
@@ -790,7 +939,7 @@ var UnlimitedClient = class {
         selected: body.selected,
         probability: body.probability,
         nextHeartbeatAtMs: body.nextHeartbeatAtMs,
-        lastVideoId: body.selected && typeof payload.videoId === "string" ? payload.videoId : void 0,
+        ...body.selected && changeKey ? { lastReportedChangeKey: changeKey } : {},
         expiresAtMs: this.now().getTime() + 24 * 60 * 60 * 1e3
       });
       return {

package/dist/sessionDecisionCache.d.ts

@@ -1,7 +1,7 @@
 import type { CacheApiLike } from './cache.js';
 export interface SessionDecision {
     expiresAtMs: number;
-    lastVideoId?: string;
+    lastReportedChangeKey?: string;
     nextHeartbeatAtMs: number;
     probability: number;
     selected: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultdai/pulse",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "files": ["dist", "README.md"],
   "publishConfig": { "access": "public" },
@@ -14,7 +14,7 @@
   },
   "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",
+    "prepack": "corepack pnpm --dir ../../libs/contracts run build && corepack pnpm run build",
     "test": "vitest run test --exclude 'dist/**'",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },