@ossy/sdk-react 1.40.2 → 3.0.1

package/README.md

@@ -1,11 +1,11 @@
 # React bindings
 
-Thin React layer over `@ossy/sdk`. One hook — **`useSdk()`** — for reads, writes, and cache invalidation.
+Thin React layer over `@ossy/sdk`. One hook — **`useSdk()`** — for reads, writes, cache invalidation, and optimistic updates.
 
 ## Getting started
 
 ```bash
-npm install @ossy/sdk-react @ossy/sdk
+npm install @ossy/sdk-react @ossy/sdk @ossy/fold
 ```
 
 ```jsx
@@ -45,17 +45,25 @@ function MyComponent() {
 }
 ```
 
+`WorkspaceProvider` provides the SDK and shared read cache. **SSE push invalidation is off by default** — enable it only where you need live cross-tab cache updates.
+
 ## API
 
 | Export | Purpose |
 |---|---|
-| `WorkspaceProvider` | Provides SDK + shared read cache |
-| `useSdk()` | Returns `{ invoke, read, invalidate, cacheKey, sdk }` |
+| `WorkspaceProvider` | Provides SDK + shared read cache (optional app-wide push via `enablePushInvalidation`) |
+| `PushInvalidationSubscriber` | Opt-in SSE invalidation for a page or subtree |
+| `useSdk()` | Returns `{ invoke, invokeOptimistic, read, invalidate, cacheKey, sdk }` |
 | `useRead()` | Same as `sdk.read` — hook for reactive reads |
+| `usePushInvalidation()` | Low-level hook; prefer `PushInvalidationSubscriber` |
 | `cacheKey(action, payload)` | Stable cache key for an action + payload |
-| `ReactSdk` | Browser SDK with `invoke(action, payload)` |
+| `projectionKey(projectionId, scopeId)` | Cache key for projection reads |
+| `applyOptimisticResource()` | Fold a pending event into cached resource state |
+| `rollbackOptimisticResource()` | Restore cache entry after failed optimistic invoke |
+| `useReadCacheStore()` | Access the shared read-cache store inside `<Cache>` |
+| `ReactSdk` | Browser SDK with `invoke` and `subscribePush` |
 | `ActionRef` | Platform action POJO type `{ id, access? }` |
-| `resolveActionId()` | Normalize dot ids to slash (`booking.create` → `booking/create`) |
+| `resolveActionId()` | Normalize dot ids to slash (`@ossy.booking.actions.create` → `@ossy/booking/actions/create`) |
 | `AsyncStatus` | Loading state constants for UI |
 | `normalizeLocation()` | Normalize resource location paths |
 | `stableSerialize()` | Deterministic JSON for cache keys |
@@ -71,6 +79,14 @@ const { status, data, error, refetch } = sdk.read(ListResources, { location })
 // Command
 await sdk.invoke(CreateResource, payload)
 
+// Optimistic command — folds pending event into cached resource, rolls back on error
+await sdk.invokeOptimistic(UpdateResource, payload, {
+  type: '@ossy/booking/schema/booking',
+  resourceId: 'booking-1',
+  event: 'Updated',
+  payload: { status: 'confirmed' },
+})
+
 // Invalidate cache (triggers re-fetch on next read)
 sdk.invalidate('location:/@ossy/domains/')
 sdk.invalidate(sdk.cacheKey(ListResources, { location }))
@@ -78,19 +94,78 @@ sdk.invalidate(sdk.cacheKey(ListResources, { location }))
 
 `read` is a React hook — call it unconditionally at the top of your component (same rules as `useState`).
 
+## Push invalidation
+
+Push invalidation (ADR 0008 §9) opens a long-lived SSE connection to `GET /events` per subscriber. **It is disabled by default** because most pages only need fresh data after their own writes (`sdk.invalidate()` / refetch).
+
+### When to enable
+
+Use push only on pages or components that benefit from **background or cross-tab** updates, for example:
+
+- Collaborative resource lists that should refresh when another user edits
+- Long-lived dashboards or inbox views
+- Dev tooling that watches task runs or automation
+
+Avoid enabling it on static marketing pages, auth flows, or one-shot forms.
+
+### Page-level (recommended)
+
+```jsx
+import { PushInvalidationSubscriber } from '@ossy/sdk-react'
+
+export default function ResourcesPage() {
+  return (
+    <>
+      <PushInvalidationSubscriber />
+      {/* … */}
+    </>
+  )
+}
+```
+
+Requires `workspaceId` on the SDK (or same-origin workspace cookie). Must render inside `WorkspaceProvider`.
+
+### App-wide (optional)
+
+In `src/config.js`:
+
+```js
+export default {
+  enablePushInvalidation: true,
+}
+```
+
+Or pass `enablePushInvalidation` to `WorkspaceProvider` in custom setups.
+
+### Manual wiring
+
+```tsx
+import { usePushInvalidation, useReadCacheStore } from '@ossy/sdk-react'
+
+function MyBridge({ sdk }) {
+  const store = useReadCacheStore()
+  usePushInvalidation(sdk, store)
+  return null
+}
+```
+
+See [@ossy/sdk README](../sdk/README.md#push-invalidation-adr-0008) for server-side details.
+
 ## Cache key conventions
 
 | Action + payload | Cache key |
 |---|---|
-| `resources/list` + `{ location }` | `location:${normalizeLocation(location)}` |
-| `resources/search` + query | `search:${stableSerialize(query)}` |
-| `resources/get` + `{ id }` | `resource:${id}` |
+| `@ossy/resources/actions/list` + `{ location }` | `location:${normalizeLocation(location)}` |
+| `@ossy/resources/actions/search` + query | `search:${stableSerialize(query)}` |
+| `@ossy/resources/actions/get` + `{ resourceId \| id }` | `resource:${resourceId}` |
+| `@ossy/booking/actions/list` | `action:@ossy/booking/actions/list` |
+| `@ossy/platform/actions/list-task-runs` + `{ workspaceId }` | `projection:@ossy/platform/data/task-run-list:${workspaceId}` |
 | default | `action:${actionId}` or `action:${actionId}:${stableSerialize(payload)}` |
 
-Import action POJOs from feature packages (`@ossy/resources`, `@ossy/workspaces`, …). Action ids use slash notation (`booking/create`).
+Import action POJOs from feature packages (`@ossy/resources`, `@ossy/workspaces`, …). Action ids use canonical `@ossy/{package}/actions/...` notation.
 
 ## Dependencies
 
-Peer dependencies: `@ossy/sdk`, `react`, `react-dom`.
+Peer dependencies: `@ossy/sdk`, `@ossy/fold`, `react`, `react-dom`.
 
 No Ramda.

package/build/node_modules/tslib/tslib.es6.js

@@ -1 +1 @@
-var r=function(){return r=Object.assign||function(r){for(var t,e=1,n=arguments.length;e<n;e++)for(var o in t=arguments[e])Object.prototype.hasOwnProperty.call(t,o)&&(r[o]=t[o]);return r},r.apply(this,arguments)};"function"==typeof SuppressedError&&SuppressedError;export{r as __assign};
+var t=function(){return t=Object.assign||function(t){for(var e,n=1,r=arguments.length;n<r;n++)for(var o in e=arguments[n])Object.prototype.hasOwnProperty.call(e,o)&&(t[o]=e[o]);return t},t.apply(this,arguments)};function e(t,e,n,r){return new(n||(n=Promise))(function(o,a){function u(t){try{i(r.next(t))}catch(t){a(t)}}function c(t){try{i(r.throw(t))}catch(t){a(t)}}function i(t){var e;t.done?o(t.value):(e=t.value,e instanceof n?e:new n(function(t){t(e)})).then(u,c)}i((r=r.apply(t,e||[])).next())})}function n(t,e){var n,r,o,a={label:0,sent:function(){if(1&o[0])throw o[1];return o[1]},trys:[],ops:[]},u=Object.create(("function"==typeof Iterator?Iterator:Object).prototype);return u.next=c(0),u.throw=c(1),u.return=c(2),"function"==typeof Symbol&&(u[Symbol.iterator]=function(){return this}),u;function c(c){return function(i){return function(c){if(n)throw new TypeError("Generator is already executing.");for(;u&&(u=0,c[0]&&(a=0)),a;)try{if(n=1,r&&(o=2&c[0]?r.return:c[0]?r.throw||((o=r.return)&&o.call(r),0):r.next)&&!(o=o.call(r,c[1])).done)return o;switch(r=0,o&&(c=[2&c[0],o.value]),c[0]){case 0:case 1:o=c;break;case 4:return a.label++,{value:c[1],done:!1};case 5:a.label++,r=c[1],c=[0];continue;case 7:c=a.ops.pop(),a.trys.pop();continue;default:if(!(o=a.trys,(o=o.length>0&&o[o.length-1])||6!==c[0]&&2!==c[0])){a=0;continue}if(3===c[0]&&(!o||c[1]>o[0]&&c[1]<o[3])){a.label=c[1];break}if(6===c[0]&&a.label<o[1]){a.label=o[1],o=c;break}if(o&&a.label<o[2]){a.label=o[2],a.ops.push(c);break}o[2]&&a.ops.pop(),a.trys.pop();continue}c=e.call(t,a)}catch(t){c=[6,t],r=0}finally{n=o=0}if(5&c[0])throw c[1];return{value:c[0]?c[1]:void 0,done:!0}}([c,i])}}}"function"==typeof SuppressedError&&SuppressedError;export{t as __assign,e as __awaiter,n as __generator};

package/build/packages/sdk-react/src/PushInvalidationSubscriber.js

@@ -0,0 +1 @@
+import{useContext as r}from"react";import{Context as o}from"./WorkspaceProvider.js";import{usePushInvalidation as t}from"./usePushInvalidation.js";import{useReadCacheStore as i}from"./Cache.js";function m(){var m=r(o).sdk,e=i();return t(m,e),null}export{m as PushInvalidationSubscriber};

package/build/packages/sdk-react/src/WorkspaceProvider.js

@@ -1 +1 @@
-import r,{createContext as e,useMemo as t}from"react";import{createCache as o}from"./Cache.js";import{createMapCache as m}from"./cacheUtils.js";import{ReactSdk as c}from"./react-sdk.js";var n=e({}),a=o(m()),i=function(e){var o=e.sdk,m=e.children,i=t(function(){return c.from(o)},[o]);return r.createElement(a,null,r.createElement(n.Provider,{value:{sdk:i}},m))};export{n as Context,i as WorkspaceProvider};
+import r,{createContext as e,useMemo as t}from"react";import{createCache as n,useReadCacheStore as o}from"./Cache.js";import{createMapCache as a}from"./cacheUtils.js";import{ReactSdk as i}from"./react-sdk.js";import{usePushInvalidation as m}from"./usePushInvalidation.js";var l=e({}),s=n(a());function c(r){var e=r.sdk,t=o();return m(e,t),null}var u=function(e){var n=e.sdk,o=e.enablePushInvalidation,a=void 0!==o&&o,m=e.children,u=t(function(){return i.from(n)},[n]);return r.createElement(s,null,r.createElement(l.Provider,{value:{sdk:u}},a&&r.createElement(c,{sdk:u}),m))};export{l as Context,u as WorkspaceProvider};

package/build/packages/sdk-react/src/asyncStatus.js

@@ -1 +1 @@
-var i={NotInitialized:"NotInitialized",Loading:"Loading",Success:"Success",Error:"Error"};export{i as AsyncStatus};
+var i={NotInitialized:"NotInitialized",Loading:"Loading",Submitting:"Submitting",Success:"Success",Error:"Error"};export{i as AsyncStatus};

package/build/packages/sdk-react/src/cacheEntry.js

@@ -1 +1 @@
-var t=function(){return{status:"NotInitialized",data:void 0,error:null}};export{t as emptyEntry};
+import{AsyncStatus as t}from"./asyncStatus.js";var r=Object.freeze({status:t.NotInitialized,data:void 0,error:null}),e=function(){return r};export{r as NOT_INITIALIZED_ENTRY,e as emptyEntry};

package/build/packages/sdk-react/src/cacheKey.js

@@ -1 +1 @@
-import{resolveActionId as o}from"./action.js";import{normalizeLocation as r}from"./normalizeLocation.js";import{stableSerialize as t}from"./stableSerialize.js";function c(c,n){var i=o(c);if("resources/list"===i){var a=null==n?void 0:n.location;return"location:".concat(r("string"==typeof a?a:void 0))}if("resources/search"===i)return"search:".concat(t(null!=n?n:{}));if("resources/get"===i){var e=null==n?void 0:n.id;return"resource:".concat(null!=e?e:"")}var s=t(n);return s?"action:".concat(i,":").concat(s):"action:".concat(i)}export{c as cacheKey};
+import{resolveActionId as o}from"./action.js";import{normalizeLocation as t}from"./normalizeLocation.js";import{stableSerialize as n}from"./stableSerialize.js";function r(o,t){return"projection:".concat(o,":").concat(t)}function s(s,i){var c,a=o(s);if("@ossy/resources/actions/list"===a){var e=null==i?void 0:i.location;return"location:".concat(t("string"==typeof e?e:void 0))}if("@ossy/resources/actions/search"===a)return"search:".concat(n(null!=i?i:{}));if("@ossy/resources/actions/get"===a){var l=null!==(c=null==i?void 0:i.resourceId)&&void 0!==c?c:null==i?void 0:i.id;return"resource:".concat(null!=l?l:"")}if("@ossy/booking/actions/list"===a)return"action:@ossy/booking/actions/list";if("@ossy/platform/actions/list-task-runs"===a){var u=null==i?void 0:i.workspaceId;return r("@ossy/platform/data/task-run-list",String(null!=u?u:""))}var f=n(i);return f?"action:".concat(a,":").concat(f):"action:".concat(a)}export{s as cacheKey,r as projectionKey};

package/build/packages/sdk-react/src/optimisticResource.js

@@ -0,0 +1 @@
+import{__assign as r}from"../../../node_modules/tslib/tslib.es6.js";import{fold as s}from"@ossy/fold";import{AsyncStatus as e}from"./asyncStatus.js";import{cacheKey as t}from"./cacheKey.js";function o(o,n){var u,a,i,c=t({id:"@ossy/resources/actions/get"},{resourceId:n.resourceId}),d=o.getEntry(c);if(d.status!==e.Success||null==d.data)return null;var l=d,f=s(d.data,r(r({},n),{id:n.resourceId,version:null!==(u=n.version)&&void 0!==u?u:(null!==(a=d.data.version)&&void 0!==a?a:0)+1,created:null!==(i=n.created)&&void 0!==i?i:Date.now()}));return o.setEntry(c,{status:e.Success,data:f,error:null}),l}function n(r,s,e){if(e){var o=t({id:"@ossy/resources/actions/get"},{resourceId:s});r.setEntry(o,e)}}export{o as applyOptimisticResource,n as rollbackOptimisticResource};

package/build/packages/sdk-react/src/public.index.js

@@ -1 +1 @@
-export{AsyncStatus}from"./asyncStatus.js";export{normalizeLocation}from"./normalizeLocation.js";export{ReactSdk}from"./react-sdk.js";export{resolveActionId,toActionRef}from"./action.js";export{Context,WorkspaceProvider}from"./WorkspaceProvider.js";export{useSdk}from"./useSdk.js";export{useRead}from"./useRead.js";export{cacheKey}from"./cacheKey.js";export{stableSerialize}from"./stableSerialize.js";
+export{AsyncStatus}from"./asyncStatus.js";export{normalizeLocation}from"./normalizeLocation.js";export{ReactSdk}from"./react-sdk.js";export{resolveActionId,toActionRef}from"./action.js";export{Context,WorkspaceProvider}from"./WorkspaceProvider.js";export{PushInvalidationSubscriber}from"./PushInvalidationSubscriber.js";export{useSdk}from"./useSdk.js";export{useRead}from"./useRead.js";export{usePushInvalidation}from"./usePushInvalidation.js";export{applyOptimisticResource,rollbackOptimisticResource}from"./optimisticResource.js";export{cacheKey,projectionKey}from"./cacheKey.js";export{stableSerialize}from"./stableSerialize.js";export{useReadCacheStore}from"./Cache.js";

package/build/packages/sdk-react/src/react-sdk.js

@@ -1 +1 @@
-import{SDK as e}from"@ossy/sdk";import{toActionRef as t}from"./action.js";export{resolveActionId}from"./action.js";var o=function(){function o(e){this.sdk=e}return Object.defineProperty(o.prototype,"workspaceId",{get:function(){return this.sdk.workspaceId},enumerable:!1,configurable:!0}),Object.defineProperty(o.prototype,"authorization",{get:function(){return this.sdk.authorization},enumerable:!1,configurable:!0}),o.prototype.updateConfig=function(e){return this.sdk.updateConfig(e),this},o.prototype.invoke=function(e,o){return this.sdk.invoke(t(e),o)},Object.defineProperty(o.prototype,"resources",{get:function(){return this.sdk.resources},enumerable:!1,configurable:!0}),o.from=function(e){return e instanceof o?e:new o(e)},o.of=function(t){return new o(e.of(t))},o}();export{o as ReactSdk};
+import{SDK as e}from"@ossy/sdk";import{toActionRef as t}from"./action.js";export{resolveActionId}from"./action.js";var r=function(){function r(e){this.sdk=e}return Object.defineProperty(r.prototype,"workspaceId",{get:function(){return this.sdk.workspaceId},enumerable:!1,configurable:!0}),Object.defineProperty(r.prototype,"authorization",{get:function(){return this.sdk.authorization},enumerable:!1,configurable:!0}),Object.defineProperty(r.prototype,"baseUrl",{get:function(){return this.sdk.baseUrl},enumerable:!1,configurable:!0}),r.prototype.subscribePush=function(e){return this.sdk.subscribePush(e)},r.prototype.updateConfig=function(e){return this.sdk.updateConfig(e),this},r.prototype.invoke=function(e,r){return this.sdk.invoke(t(e),r)},Object.defineProperty(r.prototype,"resources",{get:function(){return this.sdk.resources},enumerable:!1,configurable:!0}),r.from=function(e){return e instanceof r?e:new r(e)},r.of=function(t){return new r(e.of(t))},r}();export{r as ReactSdk};

package/build/packages/sdk-react/src/usePushInvalidation.js

@@ -0,0 +1 @@
+import{useEffect as i}from"react";function n(n,o){i(function(){if((null==n?void 0:n.workspaceId)&&"function"==typeof n.subscribePush)return n.subscribePush({onMessage:function(i){var n;(null===(n=null==i?void 0:i.invalidate)||void 0===n?void 0:n.length)&&o.invalidate(i.invalidate)}})},[n,o])}export{n as usePushInvalidation};

package/build/packages/sdk-react/src/useRead.js

@@ -1 +1 @@
-import{useContext as t,useMemo as r,useCallback as n,useSyncExternalStore as o,useEffect as e}from"react";import{toActionRef as s}from"./action.js";import{AsyncStatus as a}from"./asyncStatus.js";import{cacheKey as u}from"./cacheKey.js";import{useReadCacheStore as c}from"./Cache.js";import{Context as i}from"./WorkspaceProvider.js";function f(f,m,d){var p=t(i).sdk,v=c(),h=r(function(){return u(f,m)},[f,m]),j=!1!==(null==d?void 0:d.enabled),k=n(function(){return v.getEntry(h)},[v,h]),l=o(v.subscribe,k,k);e(function(){j&&l.status!==a.Loading&&l.status!==a.Success&&l.status!==a.Error&&v.fetch(h,function(){return p.invoke(s(f),m)}).catch(function(){})},[j,h,l.status,v,p,f,m]);var b=n(function(){return v.invalidate(h),v.fetch(h,function(){return p.invoke(s(f),m)})},[v,h,p,f,m]);return{status:l.status,data:l.data,error:l.error,refetch:b}}export{u as cacheKey,f as useRead};
+import{useContext as t,useMemo as r,useCallback as o,useSyncExternalStore as n,useEffect as e}from"react";import{toActionRef as s}from"./action.js";import{AsyncStatus as a}from"./asyncStatus.js";import{cacheKey as i}from"./cacheKey.js";import{useReadCacheStore as u}from"./Cache.js";import{Context as c}from"./WorkspaceProvider.js";import{stableSerialize as f}from"./stableSerialize.js";function m(m,p,d){var l=t(c).sdk,v=u(),h=f(null!=p?p:{}),j=r(function(){return i(m,p)},[m,h]),b=!1!==(null==d?void 0:d.enabled),k=o(function(){return v.getEntry(j)},[v,j]),y=n(v.subscribe,k,k);e(function(){b&&y.status!==a.Loading&&y.status!==a.Success&&y.status!==a.Error&&v.fetch(j,function(){return l.invoke(s(m),p)}).catch(function(){})},[b,j,y.status,v,l,m,h]);var S=o(function(){return v.invalidate(j),v.fetch(j,function(){return l.invoke(s(m),p)})},[v,j,l,m,h]);return{status:y.status,data:y.data,error:y.error,refetch:S}}export{i as cacheKey,m as useRead};

package/build/packages/sdk-react/src/useSdk.js

@@ -1 +1 @@
-import{useContext as r,useCallback as e,useMemo as o}from"react";import{cacheKey as i}from"./cacheKey.js";import{Context as t}from"./WorkspaceProvider.js";import{useReadCacheStore as n}from"./Cache.js";import{useRead as a}from"./useRead.js";function c(){var c=r(t).sdk,m=n(),f=e(function(r){m.invalidate(r)},[m]),s=e(function(r,e){return c.invoke(r,e)},[c]);return o(function(){return{invoke:s,read:a,invalidate:f,cacheKey:i,sdk:c}},[s,f,c])}export{c as useSdk};
+import{__awaiter as e,__generator as r}from"../../../node_modules/tslib/tslib.es6.js";import{useContext as t,useRef as o,useCallback as i,useMemo as n}from"react";import{cacheKey as s}from"./cacheKey.js";import{Context as c}from"./WorkspaceProvider.js";import{useReadCacheStore as u}from"./Cache.js";import{useRead as a}from"./useRead.js";import{rollbackOptimisticResource as d,applyOptimisticResource as m}from"./optimisticResource.js";function l(){var l=this,f=t(c).sdk,p=u(),v=o(new Map),h=i(function(e){p.invalidate(e)},[p]),k=i(function(e,r){return f.invoke(e,r)},[f]),j=i(function(t,o,i){return e(l,void 0,void 0,function(){var e,n;return r(this,function(r){switch(r.label){case 0:e=null,(null==i?void 0:i.resourceId)&&(e=m(p,i))&&v.current.set(i.resourceId,e),r.label=1;case 1:return r.trys.push([1,3,,4]),[4,f.invoke(t,o)];case 2:return[2,r.sent()];case 3:throw n=r.sent(),(null==i?void 0:i.resourceId)&&(d(p,i.resourceId,e),v.current.delete(i.resourceId)),n;case 4:return[2]}})})},[f,p]);return n(function(){return{invoke:k,invokeOptimistic:j,read:a,invalidate:h,cacheKey:s,sdk:f}},[k,j,h,f])}export{l as useSdk};

package/build/public.index.d.ts

@@ -1,9 +1,10 @@
-import { SDK, SDKConfig } from '@ossy/sdk';
+import { SDK, SDKConfig, PushMessage } from '@ossy/sdk';
 import React, { PropsWithChildren } from 'react';
 
 declare const AsyncStatus: {
     readonly NotInitialized: "NotInitialized";
     readonly Loading: "Loading";
+    readonly Submitting: "Submitting";
     readonly Success: "Success";
     readonly Error: "Error";
 };
@@ -29,6 +30,8 @@ declare class ReactSdk {
     constructor(sdk: SDK);
     get workspaceId(): string | undefined;
     get authorization(): string | undefined;
+    get baseUrl(): string;
+    subscribePush(handlers: Parameters<SDK['subscribePush']>[0]): () => void;
     updateConfig(config: SDKConfig): this;
     invoke<TPayload extends Record<string, unknown> = Record<string, unknown>, TResult = unknown>(action: ActionRef | string, payload?: TPayload): Promise<TResult>;
     /** @deprecated Use `invoke(action, payload)`. Kept for transitional resource uploads. */
@@ -62,10 +65,26 @@ declare const Context: React.Context<Config>;
 interface Config {
     sdk: ReactSdk;
 }
-declare const WorkspaceProvider: ({ sdk, children, }: PropsWithChildren<{
+interface WorkspaceProviderProps {
     sdk: SDK | ReactSdk;
-}>) => React.JSX.Element;
+    /**
+     * When true, subscribe to SSE push for the whole app tree.
+     * Default false — prefer {@link PushInvalidationSubscriber} on specific pages.
+     */
+    enablePushInvalidation?: boolean;
+}
+declare const WorkspaceProvider: ({ sdk, enablePushInvalidation, children, }: PropsWithChildren<WorkspaceProviderProps>) => React.JSX.Element;
 
+/**
+ * Opt-in SSE push invalidation for a page or subtree.
+ *
+ * Mount only where live cache invalidation matters (e.g. collaborative lists,
+ * long-lived dashboards). Most pages should rely on `sdk.invalidate()` after
+ * writes instead — see sdk-react README § Push invalidation.
+ */
+declare function PushInvalidationSubscriber(): null;
+
+declare function projectionKey(projectionId: string, scopeId: string): string;
 declare function cacheKey(action: ActionRef | string, payload?: Record<string, unknown>): string;
 
 interface ReadOptions {
@@ -80,8 +99,41 @@ interface ReadResult<T = unknown> {
 }
 declare function useRead<T = unknown>(action: ActionRef | string, payload?: Record<string, unknown>, options?: ReadOptions): ReadResult<T>;
 
+interface CacheEntry<T = unknown> {
+    status: AsyncStatusType;
+    data?: T;
+    error?: Error | null;
+}
+
+type Listener = () => void;
+interface ReadCacheStore {
+    getEntry: (key: string) => CacheEntry;
+    setEntry: (key: string, entry: CacheEntry | ((prev: CacheEntry) => CacheEntry)) => void;
+    invalidate: (key: string | string[]) => void;
+    subscribe: (listener: Listener) => () => void;
+    fetch: <T>(key: string, fetcher: () => Promise<T>) => Promise<T>;
+}
+declare const useReadCacheStore: () => ReadCacheStore;
+
+interface OptimisticResourceEvent {
+    type: string;
+    resourceId: string;
+    event: string;
+    version?: number;
+    payload?: Record<string, unknown>;
+    created?: number;
+    createdBy?: string;
+}
+/**
+ * Optimistically fold a pending resource event into the read cache (ADR 0008 §9).
+ * Returns rollback entry when applied.
+ */
+declare function applyOptimisticResource(store: ReadCacheStore, event: OptimisticResourceEvent): CacheEntry | null;
+declare function rollbackOptimisticResource(store: ReadCacheStore, resourceId: string, rollback: CacheEntry | null): void;
+
 interface SdkApi {
     invoke: ReactSdk['invoke'];
+    invokeOptimistic: (action: Parameters<ReactSdk['invoke']>[0], payload?: Record<string, unknown>, optimistic?: OptimisticResourceEvent) => ReturnType<ReactSdk['invoke']>;
     read: typeof useRead;
     invalidate: (key: string | string[]) => void;
     cacheKey: typeof cacheKey;
@@ -89,8 +141,18 @@ interface SdkApi {
 }
 declare function useSdk(): SdkApi;
 
+/**
+ * ADR 0008 §9 — subscribe to SSE push and invalidate read-cache keys.
+ */
+declare function usePushInvalidation(sdk: {
+    subscribePush?: (handlers: {
+        onMessage: (message: PushMessage) => void;
+    }) => () => void;
+    workspaceId?: string;
+}, store: ReadCacheStore): void;
+
 /** Deterministic JSON for cache keys — sorted object keys, no Ramda. */
 declare function stableSerialize(value: unknown): string;
 
-export { AsyncStatus, Context, ReactSdk, WorkspaceProvider, cacheKey, normalizeLocation, resolveActionId, stableSerialize, toActionRef, useRead, useSdk };
-export type { ActionRef, AsyncStatusType, Config, ReadOptions, ReadResult, SdkApi };
+export { AsyncStatus, Context, PushInvalidationSubscriber, ReactSdk, WorkspaceProvider, applyOptimisticResource, cacheKey, normalizeLocation, projectionKey, resolveActionId, rollbackOptimisticResource, stableSerialize, toActionRef, usePushInvalidation, useRead, useReadCacheStore, useSdk };
+export type { ActionRef, AsyncStatusType, Config, OptimisticResourceEvent, ReadOptions, ReadResult, SdkApi, WorkspaceProviderProps };

package/build/types/PushInvalidationSubscriber.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Opt-in SSE push invalidation for a page or subtree.
+ *
+ * Mount only where live cache invalidation matters (e.g. collaborative lists,
+ * long-lived dashboards). Most pages should rely on `sdk.invalidate()` after
+ * writes instead — see sdk-react README § Push invalidation.
+ */
+export function PushInvalidationSubscriber(): null;

package/build/types/WorkspaceProvider.d.ts

@@ -5,6 +5,12 @@ export declare const Context: React.Context<Config>;
 export interface Config {
     sdk: ReactSdk;
 }
-export declare const WorkspaceProvider: ({ sdk, children, }: PropsWithChildren<{
+export interface WorkspaceProviderProps {
     sdk: SDK | ReactSdk;
-}>) => React.JSX.Element;
+    /**
+     * When true, subscribe to SSE push for the whole app tree.
+     * Default false — prefer {@link PushInvalidationSubscriber} on specific pages.
+     */
+    enablePushInvalidation?: boolean;
+}
+export declare const WorkspaceProvider: ({ sdk, enablePushInvalidation, children, }: PropsWithChildren<WorkspaceProviderProps>) => React.JSX.Element;

package/build/types/asyncStatus.d.ts

@@ -1,6 +1,7 @@
 export declare const AsyncStatus: {
     readonly NotInitialized: "NotInitialized";
     readonly Loading: "Loading";
+    readonly Submitting: "Submitting";
     readonly Success: "Success";
     readonly Error: "Error";
 };

package/build/types/cacheEntry.d.ts

@@ -4,4 +4,6 @@ export interface CacheEntry<T = unknown> {
     data?: T;
     error?: Error | null;
 }
+/** Stable fallback for useSyncExternalStore — must not allocate per getSnapshot call. */
+export declare const NOT_INITIALIZED_ENTRY: CacheEntry;
 export declare const emptyEntry: () => CacheEntry;

package/build/types/cacheKey.d.ts

@@ -1,2 +1,3 @@
 import { type ActionRef } from './action';
+export declare function projectionKey(projectionId: string, scopeId: string): string;
 export declare function cacheKey(action: ActionRef | string, payload?: Record<string, unknown>): string;

package/build/types/optimisticResource.d.ts

@@ -0,0 +1,17 @@
+import type { ReadCacheStore } from './Cache';
+import type { CacheEntry } from './cacheEntry';
+export interface OptimisticResourceEvent {
+    type: string;
+    resourceId: string;
+    event: string;
+    version?: number;
+    payload?: Record<string, unknown>;
+    created?: number;
+    createdBy?: string;
+}
+/**
+ * Optimistically fold a pending resource event into the read cache (ADR 0008 §9).
+ * Returns rollback entry when applied.
+ */
+export declare function applyOptimisticResource(store: ReadCacheStore, event: OptimisticResourceEvent): CacheEntry | null;
+export declare function rollbackOptimisticResource(store: ReadCacheStore, resourceId: string, rollback: CacheEntry | null): void;

package/build/types/public.index.d.ts

@@ -3,7 +3,11 @@ export * from './normalizeLocation';
 export * from './react-sdk';
 export * from './action';
 export * from './WorkspaceProvider';
+export { PushInvalidationSubscriber } from './PushInvalidationSubscriber.jsx';
 export * from './useSdk';
 export * from './useRead';
+export * from './usePushInvalidation';
+export * from './optimisticResource';
 export * from './cacheKey';
 export * from './stableSerialize';
+export { useReadCacheStore } from './Cache';

package/build/types/react-sdk.d.ts

@@ -8,6 +8,8 @@ export declare class ReactSdk {
     constructor(sdk: SDK);
     get workspaceId(): string | undefined;
     get authorization(): string | undefined;
+    get baseUrl(): string;
+    subscribePush(handlers: Parameters<SDK['subscribePush']>[0]): () => void;
     updateConfig(config: SDKConfig): this;
     invoke<TPayload extends Record<string, unknown> = Record<string, unknown>, TResult = unknown>(action: ActionRef | string, payload?: TPayload): Promise<TResult>;
     /** @deprecated Use `invoke(action, payload)`. Kept for transitional resource uploads. */

package/build/types/usePushInvalidation.d.ts

@@ -0,0 +1,11 @@
+import type { PushMessage } from '@ossy/sdk';
+import type { ReadCacheStore } from './Cache';
+/**
+ * ADR 0008 §9 — subscribe to SSE push and invalidate read-cache keys.
+ */
+export declare function usePushInvalidation(sdk: {
+    subscribePush?: (handlers: {
+        onMessage: (message: PushMessage) => void;
+    }) => () => void;
+    workspaceId?: string;
+}, store: ReadCacheStore): void;

package/build/types/useSdk.d.ts

@@ -1,8 +1,10 @@
 import { cacheKey } from './cacheKey';
 import { useRead } from './useRead';
 import type { ReactSdk } from './react-sdk';
+import { type OptimisticResourceEvent } from './optimisticResource';
 export interface SdkApi {
     invoke: ReactSdk['invoke'];
+    invokeOptimistic: (action: Parameters<ReactSdk['invoke']>[0], payload?: Record<string, unknown>, optimistic?: OptimisticResourceEvent) => ReturnType<ReactSdk['invoke']>;
     read: typeof useRead;
     invalidate: (key: string | string[]) => void;
     cacheKey: typeof cacheKey;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ossy/sdk-react",
   "description": "Software Development Kit React",
-  "version": "1.40.2",
+  "version": "3.0.1",
   "url": "git://github.com/ossy-se/packages/sdk-react",
   "source": "src/public.index.ts",
   "main": "./build/packages/sdk-react/src/public.index.js",
@@ -40,7 +40,8 @@
     "@babel/preset-typescript": "^7.26.0"
   },
   "peerDependencies": {
-    "@ossy/sdk": ">=1.0.0 <2.0.0",
+    "@ossy/fold": ">=1.0.0 <4.0.0",
+    "@ossy/sdk": ">=1.0.0 <4.0.0",
     "react": ">=19.0.0 <20.0.0",
     "react-dom": ">=19.0.0 <20.0.0"
   },
@@ -52,5 +53,5 @@
     "/build",
     "README.md"
   ],
-  "gitHead": "2b8745d57fee8b6c08787e2755b4df489291a5cd"
+  "gitHead": "4a70ec216448680d2fddc57b2a8a0077489720ae"
 }