@deliverd/sdk 0.35.0 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -808,6 +808,24 @@ done.status; // "complete"
808
808
  done.decision; // "approved"
809
809
  ```
810
810
 
811
+ In React, mount it with one component from `@deliverd/sdk/react` (React 18 or
812
+ later; `react` is an optional peer dependency):
813
+
814
+ ```tsx
815
+ import { DeliverdDecision } from "@deliverd/sdk/react";
816
+
817
+ <DeliverdDecision
818
+ clientSecret={clientSecret} // embedded.clientSecret, handed down from your server
819
+ onDecided={(event) => confirmOnServer(event.sessionId)}
820
+ />;
821
+
822
+ // No account yet? The demo request: sample data, nothing recorded.
823
+ <DeliverdDecision demo onDecided={(event) => console.log(event.decision)} />;
824
+ ```
825
+
826
+ Elsewhere, `loadElements()` from `@deliverd/sdk/elements` loads the script once
827
+ and resolves to the same `mountDecision`.
828
+
811
829
  `deliverd.approvals.list({ approver: "sarah@acme.com", status: "pending" })` is
812
830
  her inbox, to show in your own UI. `deliverd.decisionSessions.expire(id)` ends a
813
831
  session early.
@@ -0,0 +1,96 @@
1
+ /**
2
+ * Deliverd Elements from a bundler: load the script, mount a decision.
3
+ *
4
+ * `https://deliverd.dev/elements/v1.js` is the element. This module does not
5
+ * reimplement it; it loads it, once, and hands back the same `mountDecision`
6
+ * a `<script>` tag would. Keeping one copy is the point: the frame, the
7
+ * origin checks on its messages and the sizing all live in that script, so a
8
+ * fix there reaches every page without anybody upgrading a package.
9
+ *
10
+ * Browser only. On a server there is no page to put a frame in, so
11
+ * `loadElements()` rejects there rather than pretending.
12
+ *
13
+ * ```ts
14
+ * import { loadElements } from "@deliverd/sdk/elements";
15
+ *
16
+ * const elements = await loadElements();
17
+ * const decision = elements.mountDecision("#decision", {
18
+ * clientSecret, // from your server: approvals.createSession(id, { mode: "embedded", origin })
19
+ * onDecided(event) {
20
+ * // Tell your server, which reads decisionSessions.get(event.sessionId) before acting.
21
+ * },
22
+ * });
23
+ * // later: decision.unmount();
24
+ * ```
25
+ */
26
+ /** Where Elements is served from, unless you say otherwise. */
27
+ export declare const ELEMENTS_ORIGIN = "https://deliverd.dev";
28
+ /** The path of the script on that origin. Versioned: v1 keeps working. */
29
+ export declare const ELEMENTS_PATH = "/elements/v1.js";
30
+ /** What every event hands your handler. */
31
+ export interface DecisionEvent {
32
+ type: "ready" | "verified" | "decided" | "expired";
33
+ sessionId: string;
34
+ approvalId: string;
35
+ /** Set on `decided`: what the approver chose. */
36
+ decision: "approved" | "rejected" | "changes_requested" | null;
37
+ /** Set on `decided`: the request's own status, which other approvers may still be part of. */
38
+ approvalStatus: string | null;
39
+ }
40
+ export interface MountDecisionOptions {
41
+ /**
42
+ * The session's `clientSecret`, from `approvals.createSession(id, { mode: "embedded", origin })`
43
+ * on your server. Required unless `demo` is set.
44
+ */
45
+ clientSecret?: string;
46
+ /**
47
+ * Show the demo request instead of a real one: sample data, a code shown on
48
+ * screen, and nothing recorded. Needs no account and frames on any site, so
49
+ * you can see the element and its events before writing server code.
50
+ */
51
+ demo?: boolean;
52
+ /** The frame's accessible title. "Decision" when omitted. */
53
+ title?: string;
54
+ /** The frame's height before it reports its own, in pixels. 320 when omitted. */
55
+ minHeight?: number;
56
+ /** Set `false` to size the frame yourself instead of letting it fit its content. */
57
+ autoResize?: boolean;
58
+ onReady?: (event: DecisionEvent) => void;
59
+ onVerified?: (event: DecisionEvent) => void;
60
+ /** The browser's word only: confirm with `decisionSessions.get(id)` from your server before acting. */
61
+ onDecided?: (event: DecisionEvent) => void;
62
+ onExpired?: (event: DecisionEvent) => void;
63
+ }
64
+ export interface MountedDecision {
65
+ frame: HTMLIFrameElement;
66
+ unmount(): void;
67
+ }
68
+ /** What the script puts on `window.Deliverd`. */
69
+ export interface DeliverdElements {
70
+ mountDecision(target: string | Element, options: MountDecisionOptions): MountedDecision;
71
+ elementsVersion: number;
72
+ }
73
+ export interface LoadElementsOptions {
74
+ /**
75
+ * Another Deliverd origin, such as your own self-hosted deployment. Must be
76
+ * the origin the session was made on: the frame only talks to the script
77
+ * that came from its own origin.
78
+ */
79
+ origin?: string;
80
+ }
81
+ /**
82
+ * Loads Elements into the page once, and resolves to its API.
83
+ *
84
+ * Safe to call as often as you like: a second call, from anywhere, waits on
85
+ * the same script rather than adding another. If the page already loaded the
86
+ * script with a `<script>` tag, that one is used.
87
+ */
88
+ export declare function loadElements(options?: LoadElementsOptions): Promise<DeliverdElements>;
89
+ /**
90
+ * Loads Elements and mounts a decision into `host`, unless `cancelled()` says
91
+ * the caller went away first. Resolves to the mounted decision, or `null`
92
+ * when it was cancelled. What the React component does in an effect, kept
93
+ * here so it can be used, and tested, without React.
94
+ */
95
+ export declare function mountWhenLoaded(host: Element, options: MountDecisionOptions, load: () => Promise<DeliverdElements>, cancelled: () => boolean): Promise<MountedDecision | null>;
96
+ //# sourceMappingURL=elements.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../src/elements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,eAAe,yBAAyB,CAAC;AAEtD,0EAA0E;AAC1E,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,QAAQ,EAAE,UAAU,GAAG,UAAU,GAAG,mBAAmB,GAAG,IAAI,CAAC;IAC/D,8FAA8F;IAC9F,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACzC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC5C,uGAAuG;IACvG,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC3C,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,iBAAiB,CAAC;IACzB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,oBAAoB,GAAG,eAAe,CAAC;IACxF,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAWD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmCzF;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,EACrC,SAAS,EAAE,MAAM,OAAO,GACvB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAOjC"}
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Deliverd Elements from a bundler: load the script, mount a decision.
3
+ *
4
+ * `https://deliverd.dev/elements/v1.js` is the element. This module does not
5
+ * reimplement it; it loads it, once, and hands back the same `mountDecision`
6
+ * a `<script>` tag would. Keeping one copy is the point: the frame, the
7
+ * origin checks on its messages and the sizing all live in that script, so a
8
+ * fix there reaches every page without anybody upgrading a package.
9
+ *
10
+ * Browser only. On a server there is no page to put a frame in, so
11
+ * `loadElements()` rejects there rather than pretending.
12
+ *
13
+ * ```ts
14
+ * import { loadElements } from "@deliverd/sdk/elements";
15
+ *
16
+ * const elements = await loadElements();
17
+ * const decision = elements.mountDecision("#decision", {
18
+ * clientSecret, // from your server: approvals.createSession(id, { mode: "embedded", origin })
19
+ * onDecided(event) {
20
+ * // Tell your server, which reads decisionSessions.get(event.sessionId) before acting.
21
+ * },
22
+ * });
23
+ * // later: decision.unmount();
24
+ * ```
25
+ */
26
+ /** Where Elements is served from, unless you say otherwise. */
27
+ export const ELEMENTS_ORIGIN = "https://deliverd.dev";
28
+ /** The path of the script on that origin. Versioned: v1 keeps working. */
29
+ export const ELEMENTS_PATH = "/elements/v1.js";
30
+ const loading = new Map();
31
+ function ready(w) {
32
+ const api = w.Deliverd;
33
+ return api && typeof api.mountDecision === "function" ? api : null;
34
+ }
35
+ /**
36
+ * Loads Elements into the page once, and resolves to its API.
37
+ *
38
+ * Safe to call as often as you like: a second call, from anywhere, waits on
39
+ * the same script rather than adding another. If the page already loaded the
40
+ * script with a `<script>` tag, that one is used.
41
+ */
42
+ export function loadElements(options = {}) {
43
+ if (typeof window === "undefined" || typeof document === "undefined") {
44
+ return Promise.reject(new Error("Deliverd Elements runs in a browser. Call loadElements() from client code."));
45
+ }
46
+ const origin = new URL(options.origin ?? ELEMENTS_ORIGIN).origin;
47
+ const w = window;
48
+ const existing = ready(w);
49
+ if (existing)
50
+ return Promise.resolve(existing);
51
+ const cached = loading.get(origin);
52
+ if (cached)
53
+ return cached;
54
+ const src = origin + ELEMENTS_PATH;
55
+ const promise = new Promise((resolve, reject) => {
56
+ const fail = (message) => {
57
+ loading.delete(origin);
58
+ reject(new Error(message));
59
+ };
60
+ const done = () => {
61
+ const api = ready(w);
62
+ if (api)
63
+ resolve(api);
64
+ else
65
+ fail(`Deliverd Elements loaded from ${src} but did not start.`);
66
+ };
67
+ let script = document.querySelector(`script[src="${src}"]`);
68
+ if (!script) {
69
+ script = document.createElement("script");
70
+ script.src = src;
71
+ script.async = true;
72
+ document.head.appendChild(script);
73
+ }
74
+ script.addEventListener("load", done, { once: true });
75
+ script.addEventListener("error", () => fail(`Could not load Deliverd Elements from ${src}.`), { once: true });
76
+ });
77
+ loading.set(origin, promise);
78
+ return promise;
79
+ }
80
+ /**
81
+ * Loads Elements and mounts a decision into `host`, unless `cancelled()` says
82
+ * the caller went away first. Resolves to the mounted decision, or `null`
83
+ * when it was cancelled. What the React component does in an effect, kept
84
+ * here so it can be used, and tested, without React.
85
+ */
86
+ export async function mountWhenLoaded(host, options, load, cancelled) {
87
+ if (!options.demo && !options.clientSecret) {
88
+ throw new Error("Deliverd: pass clientSecret (from an embedded session), or demo: true.");
89
+ }
90
+ const elements = await load();
91
+ if (cancelled())
92
+ return null;
93
+ return elements.mountDecision(host, options);
94
+ }
@@ -0,0 +1,40 @@
1
+ /**
2
+ * `<DeliverdDecision>`: a decision session in a React page.
3
+ *
4
+ * A thin wrapper over Deliverd Elements (`@deliverd/sdk/elements`): it loads
5
+ * the script once, mounts the frame into a `<div>` it renders, passes your
6
+ * handlers through, and unmounts the frame when the component goes away or
7
+ * the secret changes. The frame is still served from Deliverd's origin, so
8
+ * your page cannot read it or press its buttons, and the approver still
9
+ * proves who they are before deciding.
10
+ *
11
+ * ```tsx
12
+ * import { DeliverdDecision } from "@deliverd/sdk/react";
13
+ *
14
+ * <DeliverdDecision
15
+ * clientSecret={clientSecret} // from your server
16
+ * onDecided={(event) => confirmOnServer(event.sessionId)}
17
+ * />
18
+ *
19
+ * // No account yet? See it with sample data, nothing recorded:
20
+ * <DeliverdDecision demo onDecided={(event) => console.log(event)} />
21
+ * ```
22
+ *
23
+ * React 18 or later. Written without JSX so the package needs no build step
24
+ * of its own for it; `react` is an optional peer dependency, needed only if
25
+ * you import this entry.
26
+ */
27
+ import { type CSSProperties, type ReactElement } from "react";
28
+ import { type MountDecisionOptions } from "./elements.js";
29
+ export type { DecisionEvent } from "./elements.js";
30
+ export interface DeliverdDecisionProps extends Pick<MountDecisionOptions, "clientSecret" | "demo" | "title" | "minHeight" | "autoResize" | "onReady" | "onVerified" | "onDecided" | "onExpired"> {
31
+ /** Another Deliverd origin, such as a self-hosted deployment. https://deliverd.dev when omitted. */
32
+ origin?: string;
33
+ /** Called when the script cannot load or the options are refused. Thrown to the console otherwise. */
34
+ onError?: (error: Error) => void;
35
+ className?: string;
36
+ style?: CSSProperties;
37
+ id?: string;
38
+ }
39
+ export declare function DeliverdDecision(props: DeliverdDecisionProps): ReactElement;
40
+ //# sourceMappingURL=react.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAoC,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,OAAO,CAAC;AAChG,OAAO,EAIL,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AAEvB,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,WAAW,qBACf,SAAQ,IAAI,CACV,oBAAoB,EACpB,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,CACtH;IACD,oGAAoG;IACpG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sGAAsG;IACtG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,YAAY,CAiD3E"}
package/dist/react.js ADDED
@@ -0,0 +1,73 @@
1
+ "use client";
2
+ /**
3
+ * `<DeliverdDecision>`: a decision session in a React page.
4
+ *
5
+ * A thin wrapper over Deliverd Elements (`@deliverd/sdk/elements`): it loads
6
+ * the script once, mounts the frame into a `<div>` it renders, passes your
7
+ * handlers through, and unmounts the frame when the component goes away or
8
+ * the secret changes. The frame is still served from Deliverd's origin, so
9
+ * your page cannot read it or press its buttons, and the approver still
10
+ * proves who they are before deciding.
11
+ *
12
+ * ```tsx
13
+ * import { DeliverdDecision } from "@deliverd/sdk/react";
14
+ *
15
+ * <DeliverdDecision
16
+ * clientSecret={clientSecret} // from your server
17
+ * onDecided={(event) => confirmOnServer(event.sessionId)}
18
+ * />
19
+ *
20
+ * // No account yet? See it with sample data, nothing recorded:
21
+ * <DeliverdDecision demo onDecided={(event) => console.log(event)} />
22
+ * ```
23
+ *
24
+ * React 18 or later. Written without JSX so the package needs no build step
25
+ * of its own for it; `react` is an optional peer dependency, needed only if
26
+ * you import this entry.
27
+ */
28
+ import { createElement, useEffect, useRef } from "react";
29
+ import { loadElements, mountWhenLoaded, } from "./elements.js";
30
+ export function DeliverdDecision(props) {
31
+ const host = useRef(null);
32
+ // Handlers read through a ref, so a new arrow function on every render does not remount the frame.
33
+ const latest = useRef(props);
34
+ latest.current = props;
35
+ const { clientSecret, demo, title, minHeight, autoResize, origin } = props;
36
+ useEffect(() => {
37
+ const el = host.current;
38
+ if (!el)
39
+ return;
40
+ let cancelled = false;
41
+ let mounted = null;
42
+ const relay = (name) => (event) => latest.current[name]?.(event);
43
+ mountWhenLoaded(el, {
44
+ clientSecret,
45
+ demo,
46
+ title,
47
+ minHeight,
48
+ autoResize,
49
+ onReady: relay("onReady"),
50
+ onVerified: relay("onVerified"),
51
+ onDecided: relay("onDecided"),
52
+ onExpired: relay("onExpired"),
53
+ }, () => loadElements({ origin }), () => cancelled)
54
+ .then((result) => {
55
+ if (cancelled)
56
+ result?.unmount();
57
+ else
58
+ mounted = result;
59
+ })
60
+ .catch((err) => {
61
+ const error = err instanceof Error ? err : new Error(String(err));
62
+ if (latest.current.onError)
63
+ latest.current.onError(error);
64
+ else
65
+ console.error(error);
66
+ });
67
+ return () => {
68
+ cancelled = true;
69
+ mounted?.unmount();
70
+ };
71
+ }, [clientSecret, demo, title, minHeight, autoResize, origin]);
72
+ return createElement("div", { ref: host, className: props.className, style: props.style, id: props.id });
73
+ }
@@ -43,7 +43,7 @@
43
43
  * **Add the version here when you publish it, not before.** An entry is a
44
44
  * claim that `npm install @deliverd/sdk@x` works today.
45
45
  */
46
- export declare const PUBLISHED_TO_NPM: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.6.2", "0.7.0", "0.7.1", "0.8.0", "0.8.1", "0.8.2", "0.9.0", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.13.0", "0.14.0", "0.15.0", "0.16.0", "0.17.0", "0.18.0", "0.19.0", "0.20.0", "0.21.0", "0.22.0", "0.23.0", "0.24.0", "0.24.1", "0.25.0", "0.25.1", "0.26.0", "0.27.0", "0.28.0", "0.29.0", "0.30.0", "0.31.0", "0.32.0", "0.33.0", "0.34.0"];
46
+ export declare const PUBLISHED_TO_NPM: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0", "0.6.0", "0.6.1", "0.6.2", "0.7.0", "0.7.1", "0.8.0", "0.8.1", "0.8.2", "0.9.0", "0.10.0", "0.11.0", "0.11.1", "0.12.0", "0.13.0", "0.14.0", "0.15.0", "0.16.0", "0.17.0", "0.18.0", "0.19.0", "0.20.0", "0.21.0", "0.22.0", "0.23.0", "0.24.0", "0.24.1", "0.25.0", "0.25.1", "0.26.0", "0.27.0", "0.28.0", "0.29.0", "0.30.0", "0.31.0", "0.32.0", "0.33.0", "0.34.0", "0.35.0"];
47
47
  /**
48
48
  * A fingerprint of what each *published* version recorded.
49
49
  *
@@ -1 +1 @@
1
- {"version":3,"file":"released.d.ts","sourceRoot":"","sources":["../src/released.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,iaA2CnB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAmHzC,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAq/gCtD,CAAC"}
1
+ {"version":3,"file":"released.d.ts","sourceRoot":"","sources":["../src/released.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,2aA4CnB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqHzC,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAm9jCtD,CAAC"}