@seed-hypermedia/client 0.0.11 → 0.0.13

package/dist/capability.d.ts

@@ -1,7 +1,8 @@
 /**
- * Capability SDK — create capabilities (delegate access to other accounts).
+ * Capability SDK — create and resolve capabilities (delegate access to other accounts).
  */
 import type { HMPublishBlobsInput, HMSigner } from './hm-types';
+import type { SeedClient } from './client';
 /** Role values for capability blobs. */
 export type CapabilityRole = 'WRITER' | 'AGENT';
 export type CreateCapabilityInput = {
@@ -19,3 +20,8 @@ export type CreateCapabilityInput = {
  * The signer is the issuer granting access to the delegate.
  */
 export declare function createCapability(input: CreateCapabilityInput, signer: HMSigner): Promise<HMPublishBlobsInput>;
+/**
+ * Find a WRITER or AGENT capability for `signerAccount` on `targetAccount`.
+ * Returns the capability CID if found, undefined if not needed (same account) or not found.
+ */
+export declare function resolveCapability(client: SeedClient, targetAccount: string, signerAccount: string): Promise<string | undefined>;

package/dist/{chunk-GMPLFPEM.mjs → chunk-LCXR7GLM.mjs}

@@ -1148,6 +1148,87 @@ function isSurrogate(s, i) {
   const code = s.charCodeAt(i);
   return 55296 <= code && code <= 56319;
 }
+async function resolveHypermediaUrl(url) {
+  let latest = false;
+  let blockRef = null;
+  let blockRange = null;
+  let panel = null;
+  try {
+    const parsedUrl = new URL(url);
+    const hasVersion = parsedUrl.searchParams.has("v");
+    const hasLatest = parsedUrl.searchParams.has("l");
+    panel = parsedUrl.searchParams.get("panel");
+    if (parsedUrl.hash) {
+      const fragment = parseFragment(parsedUrl.hash.slice(1));
+      if (fragment) {
+        blockRef = fragment.blockId;
+        if ("start" in fragment && fragment.start !== void 0) {
+          blockRange = { start: fragment.start, end: fragment.end };
+        } else if ("expanded" in fragment && fragment.expanded) {
+          blockRange = { expanded: fragment.expanded };
+        }
+      }
+    }
+    latest = blockRef ? false : hasLatest || !hasVersion;
+  } catch {
+  }
+  const response = await fetch(url, {
+    method: "OPTIONS"
+  });
+  if (response.status === 200) {
+    const rawId = response.headers.get("x-hypermedia-id");
+    const id = rawId ? decodeURIComponent(rawId) : null;
+    const version = response.headers.get("x-hypermedia-version");
+    const encodedTitle = response.headers.get("x-hypermedia-title");
+    const title = encodedTitle ? decodeURIComponent(encodedTitle) : null;
+    const rawTarget = response.headers.get("x-hypermedia-target");
+    const target = rawTarget ? unpackHmId(decodeURIComponent(rawTarget)) : null;
+    const rawAuthors = response.headers.get("x-hypermedia-authors");
+    const authors = rawAuthors ? decodeURIComponent(rawAuthors).split(",").map((author) => unpackHmId(author)) : null;
+    const type = response.headers.get("x-hypermedia-type");
+    if (id) {
+      const hmId = unpackHmId(id);
+      const resolvedVersion = version ?? (hmId == null ? void 0 : hmId.version) ?? null;
+      let siteHostname = null;
+      try {
+        const inputUrl = new URL(url);
+        if (!inputUrl.pathname.startsWith("/hm/")) {
+          siteHostname = inputUrl.origin;
+        }
+      } catch {
+      }
+      return {
+        id,
+        hmId: hmId ? {
+          ...hmId,
+          version: resolvedVersion,
+          latest,
+          blockRef,
+          blockRange,
+          hostname: siteHostname || hmId.hostname
+        } : null,
+        version,
+        title,
+        target,
+        authors,
+        type,
+        panel
+      };
+    }
+    return null;
+  }
+  return null;
+}
+async function resolveId(input) {
+  const parsed = unpackHmId(input);
+  if (parsed) return parsed;
+  if (input.startsWith("http://") || input.startsWith("https://")) {
+    const resolved = await resolveHypermediaUrl(input);
+    if (resolved == null ? void 0 : resolved.hmId) return resolved.hmId;
+    throw new Error(`URL does not appear to be a Seed Hypermedia resource: ${input}`);
+  }
+  throw new Error(`Invalid Hypermedia ID: ${input}`);
+}
 
 export {
   BlockRangeSchema,
@@ -1309,5 +1390,7 @@ export {
   parseFragment,
   unpackHmId,
   codePointLength,
-  isSurrogate
+  isSurrogate,
+  resolveHypermediaUrl,
+  resolveId
 };

package/dist/hm-types.d.ts

@@ -47033,4 +47033,70 @@ export declare function unpackHmId(hypermediaId?: string): UnpackedHypermediaId
 export declare function codePointLength(entry: string): number;
 /** Check if a UTF-16 code unit at index i is the start of a surrogate pair. */
 export declare function isSurrogate(s: string, i: number): boolean;
+/** Resolve a web URL to its Hypermedia metadata via an OPTIONS request. */
+export declare function resolveHypermediaUrl(url: string): Promise<{
+    id: string;
+    hmId: {
+        version: string | null;
+        latest: boolean;
+        blockRef: string | null;
+        blockRange: {
+            start: number;
+            end: number;
+        } | {
+            expanded: boolean;
+        } | null;
+        hostname: string | null;
+        path: string[] | null;
+        id: string;
+        uid: string;
+        scheme: string | null;
+        targetDocUid?: string | null | undefined;
+        targetDocPath?: string[] | null | undefined;
+    } | null;
+    version: string | null;
+    title: string | null;
+    target: {
+        path: string[] | null;
+        version: string | null;
+        id: string;
+        uid: string;
+        blockRef: string | null;
+        blockRange: {
+            start?: number | undefined;
+            end?: number | undefined;
+            expanded?: boolean | undefined;
+        } | null;
+        hostname: string | null;
+        scheme: string | null;
+        latest?: boolean | null | undefined;
+        targetDocUid?: string | null | undefined;
+        targetDocPath?: string[] | null | undefined;
+    } | null;
+    authors: ({
+        path: string[] | null;
+        version: string | null;
+        id: string;
+        uid: string;
+        blockRef: string | null;
+        blockRange: {
+            start?: number | undefined;
+            end?: number | undefined;
+            expanded?: boolean | undefined;
+        } | null;
+        hostname: string | null;
+        scheme: string | null;
+        latest?: boolean | null | undefined;
+        targetDocUid?: string | null | undefined;
+        targetDocPath?: string[] | null | undefined;
+    } | null)[] | null;
+    type: string | null;
+    panel: string | null;
+} | null>;
+/**
+ * Resolve a string that may be an hm:// ID, a gateway URL, or a site web URL
+ * into an UnpackedHypermediaId. Tries synchronous parsing first, then falls
+ * back to an OPTIONS request for web URLs.
+ */
+export declare function resolveId(input: string): Promise<UnpackedHypermediaId>;
 export {};

package/dist/hm-types.mjs

@@ -154,12 +154,14 @@ import {
   packHmId,
   parseCustomURL,
   parseFragment,
+  resolveHypermediaUrl,
+  resolveId,
   serializeBlockRange,
   siteDiscoverRequestSchema,
   toNumber,
   unpackHmId,
   unpackedHmIdSchema
-} from "./chunk-GMPLFPEM.mjs";
+} from "./chunk-LCXR7GLM.mjs";
 export {
   BlockRangeSchema,
   BoldAnnotationSchema,
@@ -316,6 +318,8 @@ export {
   packHmId,
   parseCustomURL,
   parseFragment,
+  resolveHypermediaUrl,
+  resolveId,
   serializeBlockRange,
   siteDiscoverRequestSchema,
   toNumber,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createCapability } from './capability';
+export { createCapability, resolveCapability } from './capability';
 export type { CapabilityRole, CreateCapabilityInput } from './capability';
 export { createChange, createChangeOps, createDocumentChange, createDocumentChangeFromOps, createGenesisChange, signDocumentChange, signPreparedChange, } from './change';
 export type { CreateChangeOpsInput, CreateDocumentChangeFromOpsInput, CreateDocumentChangeInput, DocumentOperation, SignDocumentChangeInput, } from './change';
@@ -20,7 +20,7 @@ export type { GrobidOptions } from './grobid';
 export { embeddedPdfToBlocks } from './pdf-to-blocks-embedded';
 export type { EmbeddedPdfResult } from './pdf-to-blocks-embedded';
 export { trimTrailingEmptyBlocks } from './comment';
-export { codePointLength, entityQueryPathToHmIdPath, getHMQueryString, hmIdPathToEntityQueryPath, HYPERMEDIA_SCHEME, isSurrogate, packBaseId, packHmId, parseCustomURL, parseFragment, serializeBlockRange, unpackHmId, } from './hm-types';
+export { codePointLength, entityQueryPathToHmIdPath, getHMQueryString, hmIdPathToEntityQueryPath, HYPERMEDIA_SCHEME, isSurrogate, packBaseId, packHmId, parseCustomURL, parseFragment, resolveHypermediaUrl, resolveId, serializeBlockRange, unpackHmId, } from './hm-types';
 export type { HMRequest, HMSigner, UnpackedHypermediaId } from './hm-types';
 export { fileToIpfsBlobs, filesToIpfsBlobs, resolveFileLinksInBlocks, hasFileLinks } from './file-to-ipfs';
 export type { CollectedBlob } from './file-to-ipfs';

package/dist/index.mjs

@@ -13,10 +13,12 @@ import {
   packHmId,
   parseCustomURL,
   parseFragment,
+  resolveHypermediaUrl,
+  resolveId,
   serializeBlockRange,
   toNumber,
   unpackHmId
-} from "./chunk-GMPLFPEM.mjs";
+} from "./chunk-LCXR7GLM.mjs";
 
 // src/capability.ts
 import { encode as cborEncode2 } from "@ipld/dag-cbor";
@@ -70,6 +72,16 @@ async function createCapability(input, signer) {
   unsigned.sig = await signObject(signer, unsigned);
   return toPublishInput(cborEncode2(unsigned));
 }
+async function resolveCapability(client, targetAccount, signerAccount) {
+  if (targetAccount === signerAccount) return void 0;
+  const targetId = unpackHmId(`hm://${targetAccount}`);
+  if (!targetId) return void 0;
+  const caps = await client.request("ListCapabilities", { targetId });
+  const match = caps.capabilities.find(
+    (c) => c.delegate === signerAccount && (c.role === "WRITER" || c.role === "AGENT")
+  );
+  return match == null ? void 0 : match.id;
+}
 
 // src/change.ts
 import { decode as cborDecode, encode as cborEncode4 } from "@ipld/dag-cbor";
@@ -3908,8 +3920,11 @@ export {
   pdfToBlocks,
   processFulltextDocument,
   pushSpanToAnnotation,
+  resolveCapability,
   resolveDocumentState,
   resolveFileLinksInBlocks,
+  resolveHypermediaUrl,
+  resolveId,
   serializeBlockRange,
   shouldAutoLinkParent,
   signDocumentChange,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seed-hypermedia/client",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "repository": {
     "type": "git",
     "url": "https://github.com/seed-hypermedia/seed",

package/src/index.ts

@@ -1,4 +1,4 @@
-export {createCapability} from './capability'
+export {createCapability, resolveCapability} from './capability'
 export type {CapabilityRole, CreateCapabilityInput} from './capability'
 export {
   createChange,
@@ -46,6 +46,8 @@ export {
   packHmId,
   parseCustomURL,
   parseFragment,
+  resolveHypermediaUrl,
+  resolveId,
   serializeBlockRange,
   unpackHmId,
 } from './hm-types'