@proulr/sdui-contract 0.1.21 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proulr/sdui-contract",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/sdui-contract-types.ts

@@ -408,6 +408,18 @@ export type SduiScreenChromeMetaWire = {
 
 export type SduiScreenMetaWire = {
   cache_ttl_ms?: number;
+  /**
+   * Intervalo mínimo (ms) entre fetches desta tela — throttle do prefetch forçado
+   * (resume/focus), onde o `cache_ttl_ms` não chega porque o app revalida por
+   * evento, não por expiração.
+   */
+  min_fetch_interval_ms?: number;
+  /**
+   * Revisão do wire, calculada pelo bff-core a partir do mesmo digest que gera o
+   * ETag. Serve para o app comparar conteúdo entre fetches guardados no disco
+   * (onde o header HTTP não sobrevive) sem manter o ETag como estado de produto.
+   */
+  rev?: string;
   offline_policy?: SduiOfflinePolicy;
   bff?: string;
   chrome?: SduiScreenChromeMetaWire;
@@ -478,6 +490,9 @@ export type SduiScreenChromeMeta = {
 
 export type SduiScreenMeta = {
   cacheTtlMs: number;
+  minFetchIntervalMs?: number;
+  /** Revisão do wire (digest do bff-core) — mesma origem do ETag da resposta. */
+  rev?: string;
   offlinePolicy: SduiOfflinePolicy;
   bff?: string;
   chrome?: SduiScreenChromeMeta;

package/src/sdui-screen-codec.test.ts

@@ -42,6 +42,25 @@ describe('decodeSduiScreenWire', () => {
     });
   });
 
+  it('maps meta.rev and throttles min_fetch_interval_ms to positive numbers', () => {
+    const screen = decodeSduiScreenWire({
+      schema_version: 1,
+      screen_id: 'chat.inbox',
+      blocks: [],
+      meta: { rev: 'abc123', min_fetch_interval_ms: 30_000 },
+    });
+    expect(screen.meta).toMatchObject({ rev: 'abc123', minFetchIntervalMs: 30_000 });
+
+    const junk = decodeSduiScreenWire({
+      schema_version: 1,
+      screen_id: 'chat.inbox',
+      blocks: [],
+      meta: { rev: '', min_fetch_interval_ms: 0 },
+    });
+    expect(junk.meta).not.toHaveProperty('rev');
+    expect(junk.meta).not.toHaveProperty('minFetchIntervalMs');
+  });
+
   it('decodes native_capability actions with capability_id', () => {
     const screen = decodeSduiScreenWire({
       schema_version: 1,

package/src/sdui-screen-codec.ts

@@ -86,8 +86,14 @@ function mapChromeMetaWire(
 }
 
 function mapMetaWire(wire: SduiScreenMetaWire | undefined): SduiScreenMeta {
+  const minFetchIntervalMs =
+    typeof wire?.min_fetch_interval_ms === 'number' && wire.min_fetch_interval_ms > 0
+      ? wire.min_fetch_interval_ms
+      : undefined;
   return {
     cacheTtlMs: wire?.cache_ttl_ms ?? DEFAULT_CACHE_TTL_MS,
+    ...(minFetchIntervalMs === undefined ? {} : { minFetchIntervalMs }),
+    ...(typeof wire?.rev === 'string' && wire.rev ? { rev: wire.rev } : {}),
     offlinePolicy: wire?.offline_policy ?? DEFAULT_OFFLINE_POLICY,
     bff: wire?.bff,
     chrome: mapChromeMetaWire(wire?.chrome),