@widgetic/embed-sdk 2.1.2 → 2.1.3

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.
@@ -22,6 +22,8 @@ export interface CompositionOwnership {
22
22
  export declare class AuthDetector {
23
23
  private authApi;
24
24
  private compositionsApi;
25
+ /** The API the clients below talk to: whether a page can read its answer to the session check depends on it. */
26
+ private readonly apiUrl;
25
27
  private sessionCache;
26
28
  private sessionCacheExpiry;
27
29
  private ownershipCache;
@@ -43,7 +43,7 @@ export declare const SDK_DEFAULTS: {
43
43
  LOG_LEVEL: "info";
44
44
  VERSION: string;
45
45
  };
46
- export declare const SDK_VERSION = "2.0.3";
46
+ export declare const SDK_VERSION = "2.1.3";
47
47
  export declare function getDefaultVersionedApiUrl(): string;
48
48
  export declare const API_DEFAULTS: {
49
49
  DEV_API_URL: string;
@@ -0,0 +1 @@
1
+ export declare const PACKAGE_VERSION = "2.1.3";
@@ -0,0 +1,15 @@
1
+ export interface EditorSessionAccessInput {
2
+ /** `window.location.hostname` of the page the SDK runs on. */
3
+ pageHostname: string;
4
+ /** The API the SDK talks to (`getApiUrl()`). */
5
+ apiUrl: string;
6
+ /** Widgetic's production API; defaults to the SDK's constant. Tests pass their own. */
7
+ productionApiUrl?: string;
8
+ /** Widgetic's own site; its host and every subdomain of it count as Widgetic's own pages. Defaults to the SDK's constant. */
9
+ widgeticSiteUrl?: string;
10
+ }
11
+ /**
12
+ * Whether a page can read the API's answer to "who is logged in", so that asking is worth a request.
13
+ * Everything unknown is answered "yes": the SDK stays quiet only where it knows the answer cannot be read.
14
+ */
15
+ export declare function canReadEditorSession(input: EditorSessionAccessInput): boolean;
@@ -0,0 +1,21 @@
1
+ /** What the SDK keeps of the person logged in. The API's session is Supabase's: `access_token` and `user` come back camel-cased. */
2
+ export interface EditorSession {
3
+ accessToken: string;
4
+ user: {
5
+ id: string;
6
+ email?: string;
7
+ [field: string]: unknown;
8
+ };
9
+ [field: string]: unknown;
10
+ }
11
+ /**
12
+ * The payload of an API answer: `data` of the `{ success, data }` envelope, or the value itself when it is not wrapped.
13
+ * An object counts as the envelope only when it has a boolean `success` and a `data` field, so a composition or a
14
+ * session that happens to have a `data` field of its own is never unwrapped by mistake.
15
+ */
16
+ export declare function unwrapApiData(body: unknown): unknown;
17
+ /**
18
+ * The logged-in person from the body of `GET /auth/session`, or `null` when nobody is logged in or the body is not a
19
+ * session (an empty `data`, an HTML page, a login answer without a user). It never throws.
20
+ */
21
+ export declare function readEditorSession(body: unknown): EditorSession | null;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Small helpers for the calls the SDK makes to the gateway's authenticated routes through the generated API client.
3
+ */
4
+ /**
5
+ * A new `Idempotency-Key` for one call.
6
+ *
7
+ * The gateway refuses a POST or a PUT on the content routes that carries none (400 `VALIDATION_FIELD_REQUIRED`,
8
+ * "Idempotency-Key header is required"), including the check that saves nothing, and it accepts 8 to 50 letters, digits,
9
+ * dashes and underscores. A UUID fits. `crypto.randomUUID` is missing in older browsers and outside secure contexts, so
10
+ * the fallback builds a version 4 shaped key from `Math.random`: the gateway only compares keys, it does not need them
11
+ * to be unguessable, and a key is never reused for a second call (a reused key would replay the first answer).
12
+ */
13
+ export declare function createIdempotencyKey(): string;
14
+ /**
15
+ * The part of a gateway answer that holds the result.
16
+ *
17
+ * The gateway wraps an answer as `{ success, data }`. This returns `data` when the answer has one and the answer itself
18
+ * when it does not (an operation the gateway answers unwrapped), so a caller reads the same fields either way.
19
+ */
20
+ export declare function unwrapGatewayAnswer(answer: Record<string, unknown>): Record<string, unknown>;
21
+ /**
22
+ * The result of a call made through the generated client's `...Raw` method, as the gateway sent it.
23
+ *
24
+ * The client's typed value is not used for these operations: it keeps only the fields its model names at the top of the
25
+ * body, and for `validateCompositionContent` and `setDynamicContent` the model describes what is inside `data` while
26
+ * the gateway sends it wrapped (`{ success, data }`), so `valid` and `validationResult` came back missing and every
27
+ * check read as invalid. An answer that is not a JSON object is read as empty.
28
+ */
29
+ export declare function readGatewayAnswer(rawResponse: Response): Promise<Record<string, unknown>>;
@@ -45,6 +45,29 @@ export declare function updateDirectMount(host: HTMLElement, nextOverlay: {
45
45
  contentItems?: unknown[];
46
46
  }): boolean;
47
47
  export declare function destroyDirectMount(host: HTMLElement): void;
48
+ /**
49
+ * The size the iframe of the same tag gets when the embed code names none (`mountIframeInto` in
50
+ * hydrate-published-host.ts passes "400" and "300"). A widget mounted in the page has the box it would have had in the
51
+ * frame, whichever way the tag is rendered, so removing `render-mode="iframe"` does not change how big the widget is.
52
+ */
53
+ export declare const DIRECT_BOX_DEFAULTS: {
54
+ readonly WIDTH_PIXELS: 400;
55
+ readonly HEIGHT_PIXELS: 300;
56
+ };
57
+ /**
58
+ * The CSS length for a `width` or `height` of an embed code. An iframe reads `height="405"` as 405px and `width="100%"`
59
+ * as a percentage; the `div` that is the box of a widget mounted in the page reads neither, so the box says it in CSS.
60
+ * A value that is not a number or a number with a unit gives the fallback, in pixels.
61
+ */
62
+ export declare function cssLengthOfEmbedAttribute(value: string | null | undefined, fallbackPixels: number): string;
63
+ /**
64
+ * The rules, in the shadow root and ahead of the module's own, that make the mount target what `#app.widgetic-root-el`
65
+ * is in the widget's frame page: it fills the box, and so does the first thing the module puts in it (the widget's root;
66
+ * a second node, such as a portal container, keeps its own size). A rule of the module's own with the same weight,
67
+ * written after these, wins. A module built before this has none of these rules of its own, which is why the SDK has
68
+ * them and not only newer builds.
69
+ */
70
+ export declare const DIRECT_BOX_STYLES = ".widgetic-direct-target { width: 100%; height: 100%; }\n.widgetic-direct-target > :first-child { width: 100%; height: 100%; min-width: 0; min-height: 0; }\n";
48
71
  /**
49
72
  * Loads the module and mounts it. Returns false when the module is missing,
50
73
  * the contract is not 2, the load fails, or the host changed while loading.
@@ -4,8 +4,14 @@
4
4
  *
5
5
  * Order:
6
6
  * 1. <script data-api-url> / window.WIDGETIC_EMBED_API (explicit override: local runs, tests)
7
- * 2. CDN lookup script (no CORS — works on CodePen)
8
- * 3. getApiUrl() / api.widgetic.com (new platform API)
7
+ * 2. getApiUrl() / api.widgetic.com (new platform API): its answer carries the embed's address, its entries and its
8
+ * adapters, and is read as soon as it comes
9
+ * 3. The CDN copy of the address (a lookup script, no CORS: it works on CodePen), for a gateway that gave no answer. A
10
+ * copy the page already holds (the script's global is set) is known before step 2 and costs nothing; one that is not
11
+ * there is requested only after step 2. Asked first, it is a round trip made before the gateway's own, and where the
12
+ * CDN holds no copy it answers 404 with an HTML page (checked on 27 October 2026 for two widgets, a quarter of a
13
+ * second each) that the browser refuses as a script (`net::ERR_BLOCKED_BY_ORB`): the wait comes before every embed,
14
+ * and the failed request shows in the console of the customer's page.
9
15
  *
10
16
  * api.widgetic.com is the new API host. Legacy REST is widgetic.com/api/v2.
11
17
  * The development gateways (the Render service, localhost:3000) are no longer
@@ -12,6 +12,12 @@ export interface AbGoalAssignment {
12
12
  }
13
13
  /** The capability a widget lists in `widgetic:ready` when it reports which element of a goal was used. */
14
14
  export declare const GOAL_REPORTER_CAPABILITY = "goal-reporter";
15
+ /** What the page changes in a running widget (`widgetic:update`): its design, its content, its list of items. */
16
+ interface WidgetUpdate {
17
+ design?: Record<string, string>;
18
+ content?: Record<string, unknown>;
19
+ contentItems?: unknown[];
20
+ }
15
21
  declare class PublishedHostBridge {
16
22
  private readonly host;
17
23
  private readonly iframe;
@@ -19,6 +25,7 @@ declare class PublishedHostBridge {
19
25
  private readonly compositionId;
20
26
  private readonly services?;
21
27
  private readyDispatched;
28
+ private pendingWidgetUpdate;
22
29
  private latestAbGoal;
23
30
  private latestWorkflowWatch;
24
31
  private attributeFlushScheduled;
@@ -42,15 +49,29 @@ declare class PublishedHostBridge {
42
49
  */
43
50
  sendWorkflowWatch(watch: WorkflowWatch): void;
44
51
  private postWorkflowWatch;
45
- sendWidgetUpdate(payload: {
46
- design?: Record<string, string>;
47
- content?: Record<string, unknown>;
48
- contentItems?: unknown[];
49
- }): void;
52
+ sendWidgetUpdate(payload: WidgetUpdate): void;
53
+ /** Sends the update the page asked for while the frame was blank, if there is one and the frame can take it now. */
54
+ private flushPendingWidgetUpdate;
55
+ /**
56
+ * Whether the frame can be written to. A frame that holds only its blank first document is on the page's own origin,
57
+ * so it refuses every message addressed to the gateway, with a warning in the customer's console (see
58
+ * `iframeStillBlank`).
59
+ */
60
+ private frameCanReceive;
50
61
  private handleWrapperMessage;
51
62
  private dispatchHostEvent;
52
63
  destroy(): void;
53
64
  }
65
+ /**
66
+ * True while the iframe still holds its initial blank document. A message addressed to the gateway has nowhere to go
67
+ * then: that window's origin is the page's own, not the gateway's, so the browser refuses it with a warning in the
68
+ * customer's console. Every default embed code met it (the page's own change of the host, such as the SDK marking it
69
+ * mounted, sent a widget update a moment after the frame was added). The bridge holds its snapshot, goal, watch and
70
+ * updates back while this is true; the `load` listener and `widgetic:ready` send them once the frame page is there. A frame
71
+ * that has gone on to the gateway is cross-origin and refuses to say where it is, and so does anything else that cannot be
72
+ * read: those are treated as loaded, which is what the bridge did before.
73
+ */
74
+ export declare function iframeStillBlank(iframe: HTMLIFrameElement): boolean;
54
75
  /**
55
76
  * Attaches the host bridge for a published iframe mount.
56
77
  *