@freqhole/haruspex 0.0.0

package/dist/protocol/messages.js

@@ -0,0 +1,255 @@
+// the unified friendz protocol message set - the normative wire-message
+// shapes for peer-to-peer presence, friend requests, knocks, and identity
+// updates. every message is validated against the same 20 fixture files
+// the rust crate's message enum was generated from
+// (haruspex/rust/fixtures/protocol/), so a message accepted here parses
+// identically on both sides of the wire.
+//
+// normalization:
+//   - the wire discriminant is a `type` field, kebab-case values.
+//   - every other field is camelCase.
+//   - every message carries `v` (defaulting to 1 when the sender omits it,
+//     for a transition window where not every peer sends it yet).
+//   - identity naming: `nodeId` everywhere; `username` for handle-like
+//     names; avatars use a blob-id reference (`avatarBlobId`) on the
+//     hello/hello-ok handshake, and an inline data url (`avatarDataUrl`)
+//     on profile-response/identity-update.
+//   - knock outcome status is `pending | accepted | denied`.
+import { z } from "zod";
+const wireVersion = z.number().int().nonnegative().default(1);
+// ---------------------------------------------------------------------------
+// shared enums
+// ---------------------------------------------------------------------------
+/** the grantable role vocabulary carried on the wire (knock-outcome, acl-change). */
+export const WireRoleSchema = z.enum(["viewer", "member", "admin", "root"]);
+/** resolution of a knock request. */
+export const WireKnockStatusSchema = z.enum(["pending", "accepted", "denied"]);
+/** whether a peer may browse without knocking first, or must knock. */
+export const BrowseCapabilitySchema = z.enum(["public", "knock"]);
+/** capability bag carried on the hello/hello-ok handshake. */
+export const CapabilitiesSchema = z.object({
+    browse: BrowseCapabilitySchema,
+});
+// ---------------------------------------------------------------------------
+// knock scope
+// ---------------------------------------------------------------------------
+/**
+ * the wire shape of a knock's scope: what access is being requested.
+ *   - account: acceptance creates or links a user identity
+ *   - browse: list access, no specific resource named
+ *   - resource: access to one named resource, with an optional requested role
+ */
+export const WireKnockScopeSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("account"),
+        requestedUsername: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal("browse"),
+    }),
+    z.object({
+        kind: z.literal("resource"),
+        resourceId: z.string(),
+        requestedRole: WireRoleSchema.optional(),
+    }),
+]);
+// ---------------------------------------------------------------------------
+// gossip digest sub-shapes
+// ---------------------------------------------------------------------------
+/** a pending-knock entry gossiped in a gossip-digest message. */
+export const GossipDigestPendingKnockSchema = z.object({
+    knockId: z.string(),
+    nodeId: z.string(),
+    username: z.string().optional(),
+    message: z.string(),
+    scope: WireKnockScopeSchema,
+    knockedAt: z.string(),
+});
+/** a profile-doc pointer entry in a gossip digest. */
+export const GossipDigestProfileEntrySchema = z.object({
+    peerNodeId: z.string(),
+    profileDocId: z.string(),
+    updatedAt: z.string(),
+});
+// ---------------------------------------------------------------------------
+// core message variants
+// ---------------------------------------------------------------------------
+const ProfileRequestSchema = z.object({
+    type: z.literal("profile-request"),
+    v: wireVersion,
+});
+const ProfileResponseSchema = z.object({
+    type: z.literal("profile-response"),
+    v: wireVersion,
+    username: z.string(),
+    bio: z.string(),
+    avatarDataUrl: z.string(),
+    accentColor: z.number().optional(),
+    profileDocId: z.string().optional(),
+    profileUpdatedAt: z.string().optional(),
+});
+const FriendRequestSchema = z.object({
+    type: z.literal("friend-request"),
+    v: wireVersion,
+    fromNodeId: z.string(),
+    fromUsername: z.string(),
+    isHub: z.boolean().optional(),
+});
+const FriendAcceptSchema = z.object({
+    type: z.literal("friend-accept"),
+    v: wireVersion,
+    fromNodeId: z.string(),
+    fromUsername: z.string(),
+    isHub: z.boolean().optional(),
+});
+const FriendAcceptAckSchema = z.object({
+    type: z.literal("friend-accept-ack"),
+    v: wireVersion,
+    fromNodeId: z.string(),
+});
+const FriendRejectSchema = z.object({
+    type: z.literal("friend-reject"),
+    v: wireVersion,
+    fromNodeId: z.string(),
+});
+const HeartbeatSchema = z.object({
+    type: z.literal("heartbeat"),
+    v: wireVersion,
+    nodeId: z.string(),
+    username: z.string(),
+    appPayload: z.unknown().optional(),
+});
+const OfflineAnnouncementSchema = z.object({
+    type: z.literal("offline-announcement"),
+    v: wireVersion,
+    nodeId: z.string(),
+});
+const HelloSchema = z.object({
+    type: z.literal("hello"),
+    v: wireVersion,
+    nodeId: z.string(),
+    username: z.string().optional(),
+    avatarBlobId: z.string().optional(),
+    capabilities: CapabilitiesSchema,
+});
+const HelloOkSchema = z.object({
+    type: z.literal("hello-ok"),
+    v: wireVersion,
+    nodeId: z.string(),
+    username: z.string().optional(),
+    avatarBlobId: z.string().optional(),
+    capabilities: CapabilitiesSchema,
+});
+const KnockRequestSchema = z.object({
+    type: z.literal("knock-request"),
+    v: wireVersion,
+    knockId: z.string(),
+    nodeId: z.string(),
+    username: z.string().optional(),
+    message: z.string(),
+    scope: WireKnockScopeSchema,
+});
+const KnockAckSchema = z.object({
+    type: z.literal("knock-ack"),
+    v: wireVersion,
+    knockId: z.string(),
+    ackerNodeId: z.string(),
+    resourceId: z.string().optional(),
+});
+const KnockOutcomeSchema = z.object({
+    type: z.literal("knock-outcome"),
+    v: wireVersion,
+    knockId: z.string().optional(),
+    status: WireKnockStatusSchema,
+    grantedRole: WireRoleSchema.optional(),
+    grantedResourceIds: z.array(z.string()).default([]),
+    byNodeId: z.string().optional(),
+});
+const IdentityUpdateSchema = z.object({
+    type: z.literal("identity-update"),
+    v: wireVersion,
+    nodeId: z.string(),
+    username: z.string().optional(),
+    avatarDataUrl: z.string().optional(),
+});
+const AclChangeSchema = z.object({
+    type: z.literal("acl-change"),
+    v: wireVersion,
+    resourceId: z.string(),
+    resourceTitle: z.string().optional(),
+    targetNodeId: z.string(),
+    newRole: WireRoleSchema.optional(),
+    changedBy: z.string(),
+    changedByUsername: z.string(),
+});
+const GossipDigestSchema = z.object({
+    type: z.literal("gossip-digest"),
+    v: wireVersion,
+    pendingKnocks: z.array(GossipDigestPendingKnockSchema).default([]),
+    profiles: z.array(GossipDigestProfileEntrySchema).default([]),
+    appPayload: z.unknown().optional(),
+});
+const BlobSeekSchema = z.object({
+    type: z.literal("blob-seek"),
+    v: wireVersion,
+    needed: z.array(z.string()).default([]),
+});
+const BlobOfferSchema = z.object({
+    type: z.literal("blob-offer"),
+    v: wireVersion,
+    available: z.array(z.string()).default([]),
+});
+const ErrorMessageSchema = z.object({
+    type: z.literal("error"),
+    v: wireVersion,
+    code: z.string(),
+    message: z.string(),
+});
+/** the discriminated union of every core (non-namespaced) friendz message. */
+export const CoreMessageSchema = z.discriminatedUnion("type", [
+    ProfileRequestSchema,
+    ProfileResponseSchema,
+    FriendRequestSchema,
+    FriendAcceptSchema,
+    FriendAcceptAckSchema,
+    FriendRejectSchema,
+    HeartbeatSchema,
+    OfflineAnnouncementSchema,
+    HelloSchema,
+    HelloOkSchema,
+    KnockRequestSchema,
+    KnockAckSchema,
+    KnockOutcomeSchema,
+    IdentityUpdateSchema,
+    AclChangeSchema,
+    GossipDigestSchema,
+    BlobSeekSchema,
+    BlobOfferSchema,
+    ErrorMessageSchema,
+]);
+/** every core message's wire `type` discriminant, in enum-declaration order. */
+export const CORE_MESSAGE_TYPES = [
+    "profile-request",
+    "profile-response",
+    "friend-request",
+    "friend-accept",
+    "friend-accept-ack",
+    "friend-reject",
+    "heartbeat",
+    "offline-announcement",
+    "hello",
+    "hello-ok",
+    "knock-request",
+    "knock-ack",
+    "knock-outcome",
+    "identity-update",
+    "acl-change",
+    "gossip-digest",
+    "blob-seek",
+    "blob-offer",
+    "error",
+];
+/** is `type` one of the core (non-namespaced) message types above? */
+export function isCoreMessageType(type) {
+    return CORE_MESSAGE_TYPES.includes(type);
+}

package/dist/protocol/messages.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=messages.test.d.ts.map

package/dist/protocol/messages.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.test.d.ts","sourceRoot":"","sources":["../../src/protocol/messages.test.ts"],"names":[],"mappings":""}

package/dist/protocol/messages.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { CoreMessageSchema, WireKnockScopeSchema, isCoreMessageType, } from "./messages.js";
+describe("CoreMessageSchema", () => {
+    it("defaults a missing v to 1", () => {
+        const parsed = CoreMessageSchema.parse({ type: "profile-request" });
+        expect(parsed).toEqual({ type: "profile-request", v: 1 });
+    });
+    it("accepts an explicit v", () => {
+        const parsed = CoreMessageSchema.parse({ type: "profile-request", v: 3 });
+        expect(parsed.v).toBe(3);
+    });
+    it("rejects a type with no matching variant", () => {
+        expect(() => CoreMessageSchema.parse({ type: "not-a-real-type" })).toThrow();
+    });
+    it("defaults missing array fields to []", () => {
+        const parsed = CoreMessageSchema.parse({ type: "blob-seek" });
+        expect(parsed).toMatchObject({ type: "blob-seek", needed: [] });
+    });
+    it("parses a full hello handshake with capabilities", () => {
+        const parsed = CoreMessageSchema.parse({
+            type: "hello",
+            v: 1,
+            nodeId: "node-abc123",
+            username: "alice",
+            capabilities: { browse: "knock" },
+        });
+        expect(parsed).toMatchObject({
+            type: "hello",
+            nodeId: "node-abc123",
+            capabilities: { browse: "knock" },
+        });
+    });
+    it("rejects hello with an invalid browse capability", () => {
+        expect(() => CoreMessageSchema.parse({
+            type: "hello",
+            nodeId: "node-abc123",
+            capabilities: { browse: "sometimes" },
+        })).toThrow();
+    });
+});
+describe("WireKnockScopeSchema", () => {
+    it("parses an account scope with an optional requestedUsername", () => {
+        expect(WireKnockScopeSchema.parse({ kind: "account" })).toEqual({ kind: "account" });
+        expect(WireKnockScopeSchema.parse({ kind: "account", requestedUsername: "bob" })).toEqual({ kind: "account", requestedUsername: "bob" });
+    });
+    it("parses a bare browse scope", () => {
+        expect(WireKnockScopeSchema.parse({ kind: "browse" })).toEqual({ kind: "browse" });
+    });
+    it("parses a resource scope with a resourceId and optional requestedRole", () => {
+        const parsed = WireKnockScopeSchema.parse({
+            kind: "resource",
+            resourceId: "doc-1",
+            requestedRole: "member",
+        });
+        expect(parsed).toEqual({ kind: "resource", resourceId: "doc-1", requestedRole: "member" });
+    });
+    it("rejects an unknown scope kind", () => {
+        expect(() => WireKnockScopeSchema.parse({ kind: "everyone" })).toThrow();
+    });
+    it("rejects an invalid role value", () => {
+        expect(() => WireKnockScopeSchema.parse({ kind: "resource", resourceId: "doc-1", requestedRole: "owner" })).toThrow();
+    });
+});
+describe("isCoreMessageType", () => {
+    it("is true for every core type", () => {
+        expect(isCoreMessageType("hello")).toBe(true);
+        expect(isCoreMessageType("knock-outcome")).toBe(true);
+    });
+    it("is false for a namespaced app-extension type", () => {
+        expect(isCoreMessageType("skein:canvas-invite")).toBe(false);
+    });
+    it("is false for an unknown type", () => {
+        expect(isCoreMessageType("not-a-real-type")).toBe(false);
+    });
+});

package/dist/share/codec.d.ts

@@ -0,0 +1,58 @@
+/** a bare node reference: "come dial this peer", nothing else. */
+export interface NodeSharePayload {
+    kind: "node";
+    nodeId: string;
+    title?: string;
+}
+/** a node id + automerge doc id, with an optional sharing-mode hint. */
+export interface DocSharePayload {
+    kind: "doc";
+    nodeId: string;
+    docId: string;
+    title?: string;
+    mode?: "public" | "knock";
+}
+/**
+ * an entity hosted on a source (a p2p node id and/or an http origin - at
+ * least one should be set so a recipient can resolve it). `entityKind` is
+ * app-defined (e.g. "album", "song", "canvas") - this package does not own
+ * a fixed vocabulary for it.
+ */
+export interface EntitySharePayload {
+    kind: "entity";
+    source: {
+        nodeId?: string;
+        httpOrigin?: string;
+    };
+    entityKind: string;
+    entityId: string;
+    parentId?: string;
+    title?: string;
+    artist?: string;
+    album?: string;
+}
+export type ShareTokenPayload = NodeSharePayload | DocSharePayload | EntitySharePayload;
+/** encode a share payload as a base64url token (no padding). */
+export declare function encodeShareToken(payload: ShareTokenPayload): string;
+/** build a url fragment for embedding in window.location.hash. */
+export declare function shareFragment(payload: ShareTokenPayload): string;
+/**
+ * strip a share url/fragment down to the bare token: handles a full url
+ * ending in a `#share/<token>` fragment, a bare `share/<token>` prefix, and
+ * a trailing `&`-joined query fragment appended after the token. returns
+ * the input unchanged (trimmed) when none of those prefixes are present,
+ * so a bare token passes through untouched.
+ */
+export declare function extractShareToken(input: string): string;
+/**
+ * decode a share token back to a payload. accepts a raw token, a
+ * `#share/<token>` fragment, or a full url ending in one. also decodes the
+ * legacy doc-share shapes (versioned `{v:1,n,d,t,m}` and the bare,
+ * unversioned `{n,d}` form) and the legacy entity-share shape
+ * (`{v:1,s:{n,h},k,i,...}`), mapping every one of them onto the current
+ * payload types. returns null on anything invalid rather than throwing, so
+ * callers can treat "not a share token" as just another input
+ * classification.
+ */
+export declare function decodeShareToken(input: string): ShareTokenPayload | null;
+//# sourceMappingURL=codec.d.ts.map

package/dist/share/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/share/codec.ts"],"names":[],"mappings":"AAiBA,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,eAAe,GAAG,kBAAkB,CAAC;AA2IxF,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAInE;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAcvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CA0CxE"}

package/dist/share/codec.js

@@ -0,0 +1,222 @@
+// unified share-link token codec.
+//
+// three token shapes exist in the wild for sharing a p2p entity via a
+// pasted string or url fragment:
+//   - a node id + an automerge doc id, with optional title/mode hints
+//   - a node id alone (a plain peer reference, no doc)
+//   - a source (p2p node id and/or http origin) plus an app-defined entity
+//     kind + id, with optional parent/title/artist/album display hints
+//
+// this codec's own wire format is versioned explicitly (`v`) so a future
+// payload addition never breaks a link already sitting in someone's
+// clipboard or browser history. decoding also recognizes the legacy token
+// shapes below, none of which carry a wire version of their own that lines
+// up with this codec's, so they are told apart by their field shape.
+import { z } from "zod";
+const CURRENT_WIRE_VERSION = 2;
+// wire schema (short keys - these end up in url bars).
+const NodeWireSchema = z.object({
+    v: z.literal(CURRENT_WIRE_VERSION),
+    k: z.literal("node"),
+    n: z.string().min(1),
+    t: z.string().optional(),
+});
+const DocWireSchema = z.object({
+    v: z.literal(CURRENT_WIRE_VERSION),
+    k: z.literal("doc"),
+    n: z.string().min(1),
+    d: z.string().min(1),
+    t: z.string().optional(),
+    m: z.enum(["public", "knock"]).optional(),
+});
+const EntityWireSchema = z.object({
+    v: z.literal(CURRENT_WIRE_VERSION),
+    k: z.literal("entity"),
+    sn: z.string().optional(),
+    sh: z.string().optional(),
+    ek: z.string().min(1),
+    i: z.string().min(1),
+    p: z.string().optional(),
+    t: z.string().optional(),
+    a: z.string().optional(),
+    al: z.string().optional(),
+});
+const WireSchema = z.discriminatedUnion("k", [NodeWireSchema, DocWireSchema, EntityWireSchema]);
+// legacy shapes this codec still decodes, so links handed out before the
+// unified codec existed keep working.
+const DocLegacyV1Schema = z.object({
+    v: z.literal(1),
+    n: z.string().min(1),
+    d: z.string().min(1),
+    t: z.string().optional(),
+    m: z.enum(["public", "knock"]).optional(),
+});
+const EntityLegacyV1Schema = z.object({
+    v: z.literal(1),
+    s: z.object({ n: z.string().optional(), h: z.string().optional() }),
+    k: z.string().min(1),
+    i: z.string().min(1),
+    p: z.string().optional(),
+    t: z.string().optional(),
+    a: z.string().optional(),
+    al: z.string().optional(),
+});
+// bare node id + doc id, no version marker at all.
+const DocBareLegacySchema = z.object({
+    n: z.string().min(1),
+    d: z.string().min(1),
+});
+function toWire(payload) {
+    switch (payload.kind) {
+        case "node":
+            return { v: CURRENT_WIRE_VERSION, k: "node", n: payload.nodeId, t: payload.title };
+        case "doc":
+            return {
+                v: CURRENT_WIRE_VERSION,
+                k: "doc",
+                n: payload.nodeId,
+                d: payload.docId,
+                t: payload.title,
+                m: payload.mode,
+            };
+        case "entity":
+            return {
+                v: CURRENT_WIRE_VERSION,
+                k: "entity",
+                sn: payload.source.nodeId,
+                sh: payload.source.httpOrigin,
+                ek: payload.entityKind,
+                i: payload.entityId,
+                p: payload.parentId,
+                t: payload.title,
+                a: payload.artist,
+                al: payload.album,
+            };
+    }
+}
+function fromWire(wire) {
+    switch (wire.k) {
+        case "node":
+            return { kind: "node", nodeId: wire.n, title: wire.t };
+        case "doc":
+            return { kind: "doc", nodeId: wire.n, docId: wire.d, title: wire.t, mode: wire.m };
+        case "entity":
+            return {
+                kind: "entity",
+                source: { nodeId: wire.sn, httpOrigin: wire.sh },
+                entityKind: wire.ek,
+                entityId: wire.i,
+                parentId: wire.p,
+                title: wire.t,
+                artist: wire.a,
+                album: wire.al,
+            };
+    }
+}
+// base64url helpers built on TextEncoder/TextDecoder rather than raw
+// btoa/atob, so a title containing non-latin1 characters round-trips
+// instead of throwing.
+function base64UrlEncode(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(token) {
+    const pad = token.length % 4 === 0 ? "" : "=".repeat(4 - (token.length % 4));
+    const b64 = token.replace(/-/g, "+").replace(/_/g, "/") + pad;
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function stripUndefined(value) {
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        if (v !== undefined)
+            out[key] = v;
+    }
+    return out;
+}
+/** encode a share payload as a base64url token (no padding). */
+export function encodeShareToken(payload) {
+    const wire = stripUndefined(toWire(payload));
+    const json = JSON.stringify(wire);
+    return base64UrlEncode(new TextEncoder().encode(json));
+}
+/** build a url fragment for embedding in window.location.hash. */
+export function shareFragment(payload) {
+    return `#share/${encodeShareToken(payload)}`;
+}
+/**
+ * strip a share url/fragment down to the bare token: handles a full url
+ * ending in a `#share/<token>` fragment, a bare `share/<token>` prefix, and
+ * a trailing `&`-joined query fragment appended after the token. returns
+ * the input unchanged (trimmed) when none of those prefixes are present,
+ * so a bare token passes through untouched.
+ */
+export function extractShareToken(input) {
+    let raw = input.trim();
+    const hashIdx = raw.indexOf("#share/");
+    if (hashIdx !== -1) {
+        raw = raw.slice(hashIdx + "#share/".length);
+    }
+    else if (raw.startsWith("share/")) {
+        raw = raw.slice("share/".length);
+    }
+    const ampIdx = raw.indexOf("&");
+    if (ampIdx !== -1)
+        raw = raw.slice(0, ampIdx);
+    return raw;
+}
+/**
+ * decode a share token back to a payload. accepts a raw token, a
+ * `#share/<token>` fragment, or a full url ending in one. also decodes the
+ * legacy doc-share shapes (versioned `{v:1,n,d,t,m}` and the bare,
+ * unversioned `{n,d}` form) and the legacy entity-share shape
+ * (`{v:1,s:{n,h},k,i,...}`), mapping every one of them onto the current
+ * payload types. returns null on anything invalid rather than throwing, so
+ * callers can treat "not a share token" as just another input
+ * classification.
+ */
+export function decodeShareToken(input) {
+    const raw = extractShareToken(input);
+    if (!raw)
+        return null;
+    let json;
+    try {
+        json = JSON.parse(new TextDecoder().decode(base64UrlDecode(raw)));
+    }
+    catch {
+        return null;
+    }
+    const wire = WireSchema.safeParse(json);
+    if (wire.success)
+        return fromWire(wire.data);
+    const docLegacy = DocLegacyV1Schema.safeParse(json);
+    if (docLegacy.success) {
+        const p = docLegacy.data;
+        return { kind: "doc", nodeId: p.n, docId: p.d, title: p.t, mode: p.m };
+    }
+    const entityLegacy = EntityLegacyV1Schema.safeParse(json);
+    if (entityLegacy.success) {
+        const p = entityLegacy.data;
+        return {
+            kind: "entity",
+            source: { nodeId: p.s.n, httpOrigin: p.s.h },
+            entityKind: p.k,
+            entityId: p.i,
+            parentId: p.p,
+            title: p.t,
+            artist: p.a,
+            album: p.al,
+        };
+    }
+    const docBareLegacy = DocBareLegacySchema.safeParse(json);
+    if (docBareLegacy.success) {
+        const p = docBareLegacy.data;
+        return { kind: "doc", nodeId: p.n, docId: p.d };
+    }
+    return null;
+}

package/dist/share/codec.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codec.test.d.ts.map

package/dist/share/codec.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.test.d.ts","sourceRoot":"","sources":["../../src/share/codec.test.ts"],"names":[],"mappings":""}