@schnsrw/casual-sheets 0.2.0

package/src/embed/EmbedTransport.unit.test.ts

@@ -0,0 +1,161 @@
+/**
+ * EmbedTransport contract tests. Mirrors the document/ repo's
+ * EmbedTransport.test.ts — wire shape is uniform across docs and
+ * sheet, only the `app` discriminator differs. When you change
+ * EmbedTransport.ts here, change it there too.
+ */
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+
+import { EmbedTransport, isCasualEnvelope } from './';
+import type { CasualEnvelope } from './';
+
+function fakeHostWindow() {
+  let handler: ((ev: unknown) => void) | null = null;
+  return {
+    addEventListener(_type: string, h: EventListenerOrEventListenerObject) {
+      handler = h as (ev: unknown) => void;
+    },
+    removeEventListener() {
+      handler = null;
+    },
+    fire(ev: unknown) {
+      if (handler) handler(ev);
+    },
+  };
+}
+
+function fakeParent() {
+  const sent: Array<{ msg: unknown; origin: string; transfer?: Transferable[] }> = [];
+  return {
+    sent,
+    postMessage(msg: unknown, origin: string, transfer?: Transferable[]) {
+      sent.push({ msg, origin, transfer });
+    },
+  };
+}
+
+test('isCasualEnvelope accepts a well-formed sheet envelope', () => {
+  assert.equal(
+    isCasualEnvelope({
+      type: 'casual.hello',
+      app: 'sheet',
+      v: 1,
+      data: {},
+    } satisfies CasualEnvelope),
+    true,
+  );
+});
+
+test('isCasualEnvelope rejects foreign types', () => {
+  assert.equal(isCasualEnvelope({ type: 'other.hello', app: 'sheet', v: 1, data: {} }), false);
+});
+
+test('isCasualEnvelope rejects bad app values', () => {
+  assert.equal(isCasualEnvelope({ type: 'casual.hello', app: 'pdf', v: 1, data: {} }), false);
+});
+
+test('EmbedTransport drops messages from disallowed origins', async () => {
+  const host = fakeHostWindow();
+  const parent = fakeParent();
+  let called = false;
+  const transport = new EmbedTransport({
+    app: 'sheet',
+    hostOrigin: 'https://drive.example',
+    version: '1.0.0',
+    commit: 'abc',
+    capabilities: [],
+    parentWindow: parent,
+    hostWindow: host,
+  });
+  transport.on({
+    onHostHello: () => {
+      called = true;
+    },
+  });
+  host.fire({
+    origin: 'https://evil.example',
+    data: { type: 'casual.hello', app: 'sheet', v: 1, data: { capabilities: [] } },
+  });
+  await new Promise((r) => setTimeout(r, 0));
+  assert.equal(called, false);
+});
+
+test('EmbedTransport routes valid host.hello + replies with editor.ready', async () => {
+  const host = fakeHostWindow();
+  const parent = fakeParent();
+  let received: unknown = null;
+  const transport = new EmbedTransport({
+    app: 'sheet',
+    hostOrigin: 'https://drive.example',
+    version: '1.0.0',
+    commit: 'abc',
+    capabilities: [],
+    parentWindow: parent,
+    hostWindow: host,
+  });
+  transport.on({
+    onHostHello: (data) => {
+      received = data;
+    },
+  });
+  host.fire({
+    origin: 'https://drive.example',
+    data: {
+      type: 'casual.hello',
+      app: 'sheet',
+      v: 1,
+      data: { capabilities: ['saveDocument'] },
+    },
+  });
+  await new Promise((r) => setTimeout(r, 0));
+  assert.deepEqual(received, { capabilities: ['saveDocument'] });
+  const lastSent = parent.sent[parent.sent.length - 1].msg as CasualEnvelope;
+  assert.equal(lastSent.type, 'casual.ready');
+  assert.equal(lastSent.app, 'sheet');
+});
+
+test('sendHello emits an editor.hello envelope', () => {
+  const host = fakeHostWindow();
+  const parent = fakeParent();
+  const transport = new EmbedTransport({
+    app: 'sheet',
+    hostOrigin: 'https://drive.example',
+    version: '1.2.3',
+    commit: 'deadbee',
+    capabilities: ['save', 'load'],
+    parentWindow: parent,
+    hostWindow: host,
+  });
+  transport.sendHello();
+  assert.equal(parent.sent.length, 1);
+  const env = parent.sent[0].msg as CasualEnvelope;
+  assert.equal(env.type, 'casual.hello');
+  assert.equal((env.data as { version: string }).version, '1.2.3');
+  assert.deepEqual((env.data as { capabilities: string[] }).capabilities, ['save', 'load']);
+});
+
+test('destroy detaches the listener', () => {
+  const host = fakeHostWindow();
+  const transport = new EmbedTransport({
+    app: 'sheet',
+    hostOrigin: 'https://drive.example',
+    version: '1.0.0',
+    commit: 'abc',
+    capabilities: [],
+    parentWindow: fakeParent(),
+    hostWindow: host,
+  });
+  let called = false;
+  transport.on({
+    onHostHello: () => {
+      called = true;
+    },
+  });
+  transport.destroy();
+  host.fire({
+    origin: 'https://drive.example',
+    data: { type: 'casual.hello', app: 'sheet', v: 1, data: { capabilities: [] } },
+  });
+  assert.equal(called, false);
+});

package/src/embed/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Embed — iframe delivery surface.
+ *
+ * EmbedTransport bridges postMessage to React handlers. The
+ * envelope shapes (`./protocol.ts`) mirror the documentation
+ * contract in `docs/internal/13-iframe-protocol.md` and the
+ * signing payloads from `../signing/types.ts`.
+ */
+
+export {
+  EmbedTransport,
+  type EmbedTransportHandlers,
+  type EmbedTransportOptions,
+} from './EmbedTransport';
+export {
+  isCasualEnvelope,
+  type CasualApp,
+  type CasualEnvelope,
+  type EditorHelloData,
+  type HostHelloData,
+  type LoadRequestData,
+  type LoadResponseData,
+  type LoadResponseDataOk,
+  type LoadResponseDataErr,
+  type SaveRequestData,
+  type SaveResponseData,
+  type SaveResponseDataOk,
+  type SaveResponseDataErr,
+  type SelectionChangedData,
+  type TelemetryEventData,
+  type LockLostData,
+  type CommandSetReadOnlyData,
+  type CommandSetThemeData,
+  type CommandSetLocaleData,
+  type SignatureRequestData,
+  type SignatureRequestAckData,
+  type SignatureFieldSignedData,
+  type SignatureCompleteData,
+  type SignatureCancelData,
+} from './protocol';

package/src/embed/protocol.ts

@@ -0,0 +1,161 @@
+/**
+ * Iframe protocol — wire envelopes that match
+ * `docs/internal/13-iframe-protocol.md`.
+ *
+ * Mirror updates to the doc whenever a new envelope shape lands.
+ * The discriminator on `type` (always starts with `casual.`) and
+ * the per-envelope `data` shape are the contract.
+ */
+
+import type {
+  CancelReason,
+  SignatureCompletePayload,
+  SignatureField,
+  SignatureMode,
+  SignedFieldPayload,
+} from '../signing/types';
+
+export type CasualApp = 'docs' | 'sheet';
+
+/** Common envelope shape — every postMessage on the wire matches this. */
+export interface CasualEnvelope<T = unknown> {
+  type: string;
+  app: CasualApp;
+  /** Per-request id for request/response correlation. Empty for fire-and-forget. */
+  id?: string;
+  /** Protocol version. Bumped only on breaking changes. */
+  v: 1;
+  data: T;
+}
+
+// ---------------------------------------------------------------
+// Handshake
+// ---------------------------------------------------------------
+
+export interface EditorHelloData {
+  capabilities: string[];
+  version: string;
+  commit: string;
+}
+
+export interface HostHelloData {
+  capabilities: string[];
+  authToken?: string;
+}
+
+// ---------------------------------------------------------------
+// Load + save (editor → host requests; host → editor responses)
+// ---------------------------------------------------------------
+
+export interface LoadRequestData {
+  docId: string;
+}
+
+export interface LoadResponseDataOk {
+  ok: true;
+  bytes: ArrayBuffer;
+  etag?: string;
+  fileName: string;
+  readOnly?: boolean;
+}
+
+export interface LoadResponseDataErr {
+  ok: false;
+  code: string;
+  message?: string;
+}
+
+export type LoadResponseData = LoadResponseDataOk | LoadResponseDataErr;
+
+export interface SaveRequestData {
+  docId: string;
+  bytes: ArrayBuffer;
+  baseEtag?: string;
+}
+
+export interface SaveResponseDataOk {
+  ok: true;
+  etag: string;
+}
+
+export interface SaveResponseDataErr {
+  ok: false;
+  code: string;
+  etag?: string;
+  message?: string;
+}
+
+export type SaveResponseData = SaveResponseDataOk | SaveResponseDataErr;
+
+// ---------------------------------------------------------------
+// Selection + telemetry + lock (editor → host notifications)
+// ---------------------------------------------------------------
+
+export interface SelectionChangedData {
+  docs?: { paraId: string; from: number; to: number; selectedText: string };
+  sheet?: { sheet: string; from: string; to: string };
+}
+
+export interface TelemetryEventData {
+  kind: string;
+  /** Arbitrary metric fields. */
+  [k: string]: unknown;
+}
+
+export interface LockLostData {
+  reason: 'taken_by_other' | 'expired' | 'host_revoked';
+}
+
+// ---------------------------------------------------------------
+// Commands (host → editor)
+// ---------------------------------------------------------------
+
+export interface CommandSetReadOnlyData {
+  readOnly: boolean;
+}
+
+export interface CommandSetThemeData {
+  theme: 'light' | 'dark' | 'system';
+}
+
+export interface CommandSetLocaleData {
+  locale: string;
+}
+
+// ---------------------------------------------------------------
+// Signing (uniform with the SDK `signing` prop)
+// ---------------------------------------------------------------
+
+export interface SignatureRequestData {
+  fields: SignatureField[];
+  mode: SignatureMode;
+  banner?: string;
+}
+
+export interface SignatureRequestAckData {
+  ok: boolean;
+  code?: string;
+}
+
+export type SignatureFieldSignedData = SignedFieldPayload;
+export type SignatureCompleteData = SignatureCompletePayload;
+
+export interface SignatureCancelData {
+  reason: CancelReason;
+}
+
+// ---------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------
+
+export function isCasualEnvelope(value: unknown): value is CasualEnvelope {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.type === 'string' &&
+    v.type.startsWith('casual.') &&
+    (v.app === 'docs' || v.app === 'sheet') &&
+    v.v === 1 &&
+    'data' in v
+  );
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @schnsrw/casual-sheets — Casual Sheets SDK
+ *
+ * Two surfaces shipped in v0.1.0:
+ *   - `./signing` — anchored cell signatures (drawn / typed / uploaded)
+ *   - `./embed`   — iframe postMessage protocol for host integrations
+ *
+ * A `CasualSheets` React component that wraps the Univer-Sheets bootstrap
+ * is planned for a follow-up release.
+ */
+
+export * from './signing';
+export * from './embed';