npm - @globalpayments/vega-sandbox-share - Versions diffs - 0.1.1-0 - Mend

@globalpayments/vega-sandbox-share 0.1.1-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.

Files changed (8) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,53 @@
+# @globalpayments/vega-sandbox-share
+Pure share-URL helper for Vega Sandbox. Composes a compact URL-hash
+payload that describes an editable file snapshot (files, contents,
+selected file, open tabs) and returns a full URL a sandbox host will
+decode on mount.
+DOM-free: relies only on `CompressionStream`, `TextEncoder`, and
+`btoa` / `atob`. Safe to bundle into any browser package.
+## Install
+```bash
+npm install @globalpayments/vega-sandbox-share
+```
+## Usage
+```ts
+import {
+  buildShareUrl,
+  type EmbedOptions,
+  type ShareState,
+} from '@globalpayments/vega-sandbox-share'
+const state: ShareState = {
+  files: ['index.html', 'src/App.jsx'],
+  fileContents: {
+    'index.html': '<!doctype html>…',
+    'src/App.jsx': 'export default function App() {…}',
+  },
+  selectedFile: 'src/App.jsx',
+  openTabs: ['src/App.jsx'],
+}
+// Build a URL that a sandbox host will decode on mount.
+const url = await buildShareUrl('/sandbox/', state, { embed: true })
+window.open(url, '_blank')
+```
+## Public API
+The public surface is intentionally minimal — one function plus the
+input/option types it needs. The runtime encode/decode primitives
+are internal implementation details of the URL protocol and are not
+exposed on the npm surface so the wire format can evolve without a
+breaking change.
+| Export | Kind | Purpose |
+|---|---|---|
+| `buildShareUrl(host, state, opts?)` | function | Compose a full URL with the encoded state in the hash. |
+| `ShareState` | type | Snapshot shape — files, contents, selected file, open tabs. |
+| `EmbedOptions` | type | Optional flags for `buildShareUrl` (`embed` / `hideTree` / `hideTerminal` / `readOnly`). |

package/dist/buildShareUrl.d.ts ADDED Viewed

@@ -0,0 +1,33 @@
+/**
+ * Build a full share URL from a {@link ShareState}.
+ *
+ * Pure: no DOM access, no `window` reads.
+ *
+ * ```ts
+ * const url = await buildShareUrl('http://localhost:5173', state, { embed: true })
+ * window.open(url, '_blank')
+ * ```
+ */
+import { type ShareState } from './shareState';
+export interface EmbedOptions {
+    /** Hide the header bar (compact layout). */
+    embed?: boolean;
+    /** Hide the file explorer sidebar. */
+    hideTree?: boolean;
+    /** Hide the terminal panel. */
+    hideTerminal?: boolean;
+    /** Make the Monaco editor read-only. */
+    readOnly?: boolean;
+}
+/**
+ * @param sandboxHost - Origin plus optional base path or filename. Examples:
+ *   - `"http://localhost:5173"`                    → `…:5173/#<hash>`
+ *   - `"https://example.com/sandbox/"`             → `…/sandbox/#<hash>`
+ *   - `"https://example.com/sandbox/index.html"`   → `…/sandbox/index.html#<hash>`
+ *
+ *   Filename-looking last segments (containing a `.`) are left untouched;
+ *   directory-looking segments get a trailing `/` appended.
+ * @param state - Snapshot to encode into the URL hash.
+ * @param embedOptions - Optional flags appended as query params.
+ */
+export declare function buildShareUrl(sandboxHost: string, state: ShareState, embedOptions?: EmbedOptions): Promise<string>;

package/dist/encoding.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+/**
+ * Pure gzip + base64url encoding helpers.
+ *
+ * DOM-free: relies only on `CompressionStream`, `TextEncoder`, and
+ * `btoa`/`atob`. Safe to bundle into any browser package.
+ */
+export declare function gzipBase64UrlEncode(input: string): Promise<string>;
+export declare function gzipBase64UrlDecode(encoded: string): Promise<string>;

package/dist/index.js ADDED Viewed

@@ -0,0 +1,31 @@
+async function d(e) {
+  const n = new CompressionStream("gzip"), r = n.writable.getWriter();
+  r.write(new TextEncoder().encode(e)), r.close();
+  const s = [], t = n.readable.getReader();
+  for (; ; ) {
+    const { done: a, value: c } = await t.read();
+    if (a) break;
+    s.push(c);
+  }
+  const o = s.reduce((a, c) => a + c.length, 0), i = new Uint8Array(o);
+  let l = 0;
+  for (const a of s)
+    i.set(a, l), l += a.length;
+  return btoa(String.fromCharCode(...i)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function h(e) {
+  return d(JSON.stringify(e));
+}
+async function f(e, n, r = {}) {
+  const s = await h(n), t = new URL(u(e));
+  return r.embed && t.searchParams.set("embed", ""), r.hideTree && t.searchParams.set("hideTree", ""), r.hideTerminal && t.searchParams.set("hideTerminal", ""), r.readOnly && t.searchParams.set("readOnly", ""), t.hash = s, t.toString();
+}
+function u(e) {
+  if (e.endsWith("/")) return e;
+  const n = e.split(/[?#]/)[0];
+  return n.slice(n.lastIndexOf("/") + 1).includes(".") ? e : e + "/";
+}
+export {
+  f as buildShareUrl
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.js","sources":["../src/encoding.ts","../src/shareState.ts","../src/buildShareUrl.ts"],"sourcesContent":["/**\n * Pure gzip + base64url encoding helpers.\n *\n * DOM-free: relies only on `CompressionStream`, `TextEncoder`, and\n * `btoa`/`atob`. Safe to bundle into any browser package.\n */\n\nexport async function gzipBase64UrlEncode(input: string): Promise<string> {\n const stream = new CompressionStream('gzip')\n const writer = stream.writable.getWriter()\n writer.write(new TextEncoder().encode(input))\n writer.close()\n const chunks: Uint8Array[] = []\n const reader = stream.readable.getReader()\n while (true) {\n const { done, value } = await reader.read()\n if (done) break\n chunks.push(value)\n }\n const total = chunks.reduce((n, c) => n + c.length, 0)\n const merged = new Uint8Array(total)\n let offset = 0\n for (const chunk of chunks) {\n merged.set(chunk, offset)\n offset += chunk.length\n }\n return btoa(String.fromCharCode(...merged))\n .replace(/\\+/g, '-')\n .replace(/\\//g, '_')\n .replace(/=+$/, '')\n}\n\nexport async function gzipBase64UrlDecode(encoded: string): Promise<string> {\n const base64 = encoded.replace(/-/g, '+').replace(/_/g, '/')\n const binary = atob(base64)\n const bytes = new Uint8Array(binary.length)\n for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)\n\n const stream = new DecompressionStream('gzip')\n const writer = stream.writable.getWriter()\n writer.write(bytes)\n writer.close()\n const chunks: Uint8Array[] = []\n const reader = stream.readable.getReader()\n while (true) {\n const { done, value } = await reader.read()\n if (done) break\n chunks.push(value)\n }\n const total = chunks.reduce((n, c) => n + c.length, 0)\n const merged = new Uint8Array(total)\n let offset = 0\n for (const chunk of chunks) {\n merged.set(chunk, offset)\n offset += chunk.length\n }\n return new TextDecoder().decode(merged)\n}\n","/**\n * Wire format for a shareable sandbox snapshot.\n *\n * A `ShareState` plus the encoding scheme in `./encoding.ts` fully\n * describes what the SPA reconstructs on load: the file list, their\n * contents, the initially selected file, and the tabs to open.\n */\n\nimport { gzipBase64UrlDecode, gzipBase64UrlEncode } from './encoding'\n\nexport interface ShareState {\n files: string[]\n fileContents: Record<string, string>\n selectedFile: string\n openTabs: string[]\n}\n\n/** Encode a {@link ShareState} into a compact URL-safe string. */\nexport async function encodeShareState(state: ShareState): Promise<string> {\n return gzipBase64UrlEncode(JSON.stringify(state))\n}\n\n/**\n * Decode a previously encoded {@link ShareState}. Returns `null` on any\n * failure (empty, corrupt, or wrong shape) so callers can fall through\n * to default state without a try/catch.\n */\nexport async function decodeShareState(hash: string): Promise<ShareState | null> {\n if (!hash) return null\n try {\n const json = await gzipBase64UrlDecode(hash)\n return JSON.parse(json) as ShareState\n } catch {\n return null\n }\n}\n","/**\n * Build a full share URL from a {@link ShareState}.\n *\n * Pure: no DOM access, no `window` reads.\n *\n * ```ts\n * const url = await buildShareUrl('http://localhost:5173', state, { embed: true })\n * window.open(url, '_blank')\n * ```\n */\n\nimport { encodeShareState, type ShareState } from './shareState'\n\nexport interface EmbedOptions {\n /** Hide the header bar (compact layout). */\n embed?: boolean\n /** Hide the file explorer sidebar. */\n hideTree?: boolean\n /** Hide the terminal panel. */\n hideTerminal?: boolean\n /** Make the Monaco editor read-only. */\n readOnly?: boolean\n}\n\n/**\n * @param sandboxHost - Origin plus optional base path or filename. Examples:\n * - `\"http://localhost:5173\"` → `…:5173/#<hash>`\n * - `\"https://example.com/sandbox/\"` → `…/sandbox/#<hash>`\n * - `\"https://example.com/sandbox/index.html\"` → `…/sandbox/index.html#<hash>`\n *\n * Filename-looking last segments (containing a `.`) are left untouched;\n * directory-looking segments get a trailing `/` appended.\n * @param state - Snapshot to encode into the URL hash.\n * @param embedOptions - Optional flags appended as query params.\n */\nexport async function buildShareUrl(\n sandboxHost: string,\n state: ShareState,\n embedOptions: EmbedOptions = {}\n): Promise<string> {\n const hash = await encodeShareState(state)\n const url = new URL(normalizeHost(sandboxHost))\n if (embedOptions.embed) url.searchParams.set('embed', '')\n if (embedOptions.hideTree) url.searchParams.set('hideTree', '')\n if (embedOptions.hideTerminal) url.searchParams.set('hideTerminal', '')\n if (embedOptions.readOnly) url.searchParams.set('readOnly', '')\n url.hash = hash\n return url.toString()\n}\n\n/** Append `/` to directory-ish paths; leave filename-ish paths untouched. */\nfunction normalizeHost(host: string): string {\n if (host.endsWith('/')) return host\n const pathOnly = host.split(/[?#]/)[0]\n const lastSegment = pathOnly.slice(pathOnly.lastIndexOf('/') + 1)\n if (lastSegment.includes('.')) return host\n return host + '/'\n}\n"],"names":["gzipBase64UrlEncode","input","stream","writer","chunks","reader","done","value","total","n","merged","offset","chunk","encodeShareState","state","buildShareUrl","sandboxHost","embedOptions","hash","url","normalizeHost","host","pathOnly"],"mappings":"AAOA,eAAsBA,EAAoBC,GAAgC;AACxE,QAAMC,IAAS,IAAI,kBAAkB,MAAM,GACrCC,IAASD,EAAO,SAAS,UAAA;AAC/B,EAAAC,EAAO,MAAM,IAAI,YAAA,EAAc,OAAOF,CAAK,CAAC,GAC5CE,EAAO,MAAA;AACP,QAAMC,IAAuB,CAAA,GACvBC,IAASH,EAAO,SAAS,UAAA;AAC/B,aAAa;AACX,UAAM,EAAE,MAAAI,GAAM,OAAAC,EAAA,IAAU,MAAMF,EAAO,KAAA;AACrC,QAAIC,EAAM;AACV,IAAAF,EAAO,KAAKG,CAAK;AAAA,EACnB;AACA,QAAMC,IAAQJ,EAAO,OAAO,CAACK,GAAG,MAAMA,IAAI,EAAE,QAAQ,CAAC,GAC/CC,IAAS,IAAI,WAAWF,CAAK;AACnC,MAAIG,IAAS;AACb,aAAWC,KAASR;AAClB,IAAAM,EAAO,IAAIE,GAAOD,CAAM,GACxBA,KAAUC,EAAM;AAElB,SAAO,KAAK,OAAO,aAAa,GAAGF,CAAM,CAAC,EACvC,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,EAAE;AACtB;ACZA,eAAsBG,EAAiBC,GAAoC;AACzE,SAAOd,EAAoB,KAAK,UAAUc,CAAK,CAAC;AAClD;ACeA,eAAsBC,EACpBC,GACAF,GACAG,IAA6B,CAAA,GACZ;AACjB,QAAMC,IAAO,MAAML,EAAiBC,CAAK,GACnCK,IAAM,IAAI,IAAIC,EAAcJ,CAAW,CAAC;AAC9C,SAAIC,EAAa,SAAOE,EAAI,aAAa,IAAI,SAAS,EAAE,GACpDF,EAAa,YAAUE,EAAI,aAAa,IAAI,YAAY,EAAE,GAC1DF,EAAa,gBAAcE,EAAI,aAAa,IAAI,gBAAgB,EAAE,GAClEF,EAAa,YAAUE,EAAI,aAAa,IAAI,YAAY,EAAE,GAC9DA,EAAI,OAAOD,GACJC,EAAI,SAAA;AACb;AAGA,SAASC,EAAcC,GAAsB;AAC3C,MAAIA,EAAK,SAAS,GAAG,EAAG,QAAOA;AAC/B,QAAMC,IAAWD,EAAK,MAAM,MAAM,EAAE,CAAC;AAErC,SADoBC,EAAS,MAAMA,EAAS,YAAY,GAAG,IAAI,CAAC,EAChD,SAAS,GAAG,IAAUD,IAC/BA,IAAO;AAChB;"}

package/dist/public.d.ts ADDED Viewed

@@ -0,0 +1,21 @@
+/**
+ * Published package entry for @globalpayments/vega-sandbox-share.
+ *
+ * Public surface — deliberately minimal:
+ *   - `buildShareUrl(host, state, opts?)` — compose a full share URL.
+ *   - `ShareState`   — snapshot shape (input type for `buildShareUrl`).
+ *   - `EmbedOptions` — optional flags for `buildShareUrl`.
+ *
+ * The runtime encode/decode primitives (`encodeShareState` /
+ * `decodeShareState`) and the raw gzip base64url helpers are
+ * intentionally NOT re-exported here. They are internal implementation
+ * details of the URL protocol shared between the URL builder and the
+ * sandbox SPA loader; keeping them off the public surface lets us
+ * evolve the wire format without a breaking change to npm consumers.
+ *
+ * Workspace-internal callers (the sandbox app) that need those
+ * lower-level helpers import from the internal `./index.ts` barrel
+ * via a Vite / Vitest alias.
+ */
+export { buildShareUrl, type EmbedOptions } from './buildShareUrl';
+export { type ShareState } from './shareState';

package/dist/shareState.d.ts ADDED Viewed

@@ -0,0 +1,21 @@
+/**
+ * Wire format for a shareable sandbox snapshot.
+ *
+ * A `ShareState` plus the encoding scheme in `./encoding.ts` fully
+ * describes what the SPA reconstructs on load: the file list, their
+ * contents, the initially selected file, and the tabs to open.
+ */
+export interface ShareState {
+    files: string[];
+    fileContents: Record<string, string>;
+    selectedFile: string;
+    openTabs: string[];
+}
+/** Encode a {@link ShareState} into a compact URL-safe string. */
+export declare function encodeShareState(state: ShareState): Promise<string>;
+/**
+ * Decode a previously encoded {@link ShareState}. Returns `null` on any
+ * failure (empty, corrupt, or wrong shape) so callers can fall through
+ * to default state without a try/catch.
+ */
+export declare function decodeShareState(hash: string): Promise<ShareState | null>;

package/package.json ADDED Viewed

@@ -0,0 +1,39 @@
+{
+  "name": "@globalpayments/vega-sandbox-share",
+  "version": "0.1.1-0",
+  "description": "Pure share-URL helpers for Vega Sandbox: build and decode URL-hash payloads that describe an editable file snapshot.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepublishOnly": "cd ../.. && npx nx run vega-sandbox-share:build"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/public.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/public.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heartlandpayments/vega-sandbox.git",
+    "directory": "packages/share"
+  },
+  "homepage": "https://github.com/heartlandpayments/vega-sandbox/tree/main/packages/share",
+  "bugs": {
+    "url": "https://github.com/heartlandpayments/vega-sandbox/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}