@ultdai/pulse 0.3.0 → 0.4.0

package/README.md

@@ -7,49 +7,51 @@ 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 } : {}),
+
+    context.waitUntil((async () => {
+      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.
+
+Konstruktor uloží nastavení bez síťového volání. První `emit()` načte povolené PulseTypes, jejich schémata a pravidla měření z autorizovaného ULTD API nebo z dosud platné sdílené cache, a teprve potom puls lokálně validuje. Neznámý typ nebo nevalidní `pulse.payload` SDK odmítne před POSTem. Vypnutý nebo nevzorkovaný puls neodešle. Další volání používají platnou konfiguraci; po expiraci se obnoví. Pokud obnova 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. Budoucí výběr katalogu podle organizace bude vycházet z identity API klíče na serveru; volající nebude předávat další token ani měnit veřejné rozhraní SDK.

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>;
@@ -552,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>;
@@ -597,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>;

package/dist/index.js

@@ -214,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(),
@@ -237,6 +238,16 @@ 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);
@@ -708,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;
@@ -842,6 +859,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);
@@ -856,7 +875,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,
@@ -913,7 +932,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.3.0",
+  "version": "0.4.0",
   "type": "module",
   "files": ["dist", "README.md"],
   "publishConfig": { "access": "public" },