sello 0.1.0 → 0.1.2

package/dist/sdk/logs.js

@@ -0,0 +1,196 @@
+import { toHex } from "../crypto/identifiers.js";
+import {
+                       
+  assertCanonicalLogUrl,
+} from "../log/canonical-url.js";
+import { MockTransparencyLog } from "../log/mock-log.js";
+import { base64urlEncode, decodeBase64url } from "./keys.js";
+
+                                             
+
+                                
+                          
+         
+                         
+                            
+                                        
+  
+
+                                   
+                    
+                  
+                                   
+                       
+  
+
+                                              
+                 
+                
+                         
+                   
+                 
+  
+
+export function memory(url        )                      {
+  return new MockTransparencyLog(toCanonicalLogUrl(url));
+}
+
+export function http(url        , options                      = {})               {
+  return new HttpSelloLog(url, options);
+}
+
+export async function queryHttpLogByTokenRef(
+  input   
+                     
+                         
+                                     
+                         
+   ,
+)                                      {
+  const fetcher = input.fetch ?? fetch;
+  const url = buildUrl(input.endpoint, `/entries?sello_token_ref=${toHex(input.tokenRef)}`);
+  const response = await fetcher(url, {
+    method: "GET",
+    headers: input.headers,
+  });
+
+  if (!response.ok) {
+    throw new TypeError(`Sello log query failed with HTTP ${response.status}`);
+  }
+
+  const decoded = await response.json();
+  if (!isRecord(decoded) || !Array.isArray(decoded.entries)) {
+    throw new TypeError("Sello log query response must contain entries");
+  }
+
+  const completeness =
+    decoded.completeness === "complete" ? "complete" : "discovery-only";
+
+  return {
+    completeness,
+    entries: decoded.entries.map(deserializeEntry),
+  };
+}
+
+export class HttpSelloLog {
+           logUrl                 ;
+           endpoint        ;
+           #headers                         ;
+           #fetch              ;
+
+  constructor(url        , options                      = {}) {
+    this.logUrl = toCanonicalLogUrl(options.logUrl ?? url);
+    this.endpoint = normalizeEndpoint(options.endpoint ?? url);
+    this.#headers = options.headers;
+    this.#fetch = options.fetch ?? fetch;
+  }
+
+  async append(
+    envelope            ,
+    integratedTime         ,
+  )                                {
+    const response = await this.#fetch(buildUrl(this.endpoint, "/entries"), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...this.#headers,
+      },
+      body: JSON.stringify({
+        logUrl: this.logUrl,
+        envelope: base64urlEncode(envelope),
+        ...(integratedTime === undefined ? {} : { integratedTime }),
+      }),
+    });
+
+    if (!response.ok) {
+      throw new TypeError(`Sello log append failed with HTTP ${response.status}`);
+    }
+
+    return deserializeEntry(await response.json());
+  }
+}
+
+export function serializeEntry(
+  entry                      ,
+)                                 {
+  return {
+    logUrl: entry.logUrl,
+    index: entry.index,
+    integratedTime: entry.integratedTime,
+    envelope: base64urlEncode(entry.envelope),
+    proof: cloneJson(entry.proof),
+  };
+}
+
+export function deserializeEntry(input         )                       {
+  if (!isRecord(input)) {
+    throw new TypeError("Sello log entry must be an object");
+  }
+
+  const { logUrl, index, integratedTime, envelope, proof } = input;
+  assertCanonicalLogUrl(logUrl, "entry.logUrl");
+
+  if (!Number.isSafeInteger(index) || index < 0) {
+    throw new TypeError("entry.index must be a non-negative safe integer");
+  }
+
+  if (
+    typeof integratedTime !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(integratedTime)
+  ) {
+    throw new TypeError("entry.integratedTime must be an RFC 3339 UTC timestamp");
+  }
+
+  if (typeof envelope !== "string") {
+    throw new TypeError("entry.envelope must be base64url");
+  }
+
+  return {
+    logUrl,
+    index,
+    integratedTime,
+    envelope: decodeBase64url(envelope, "entry.envelope"),
+    proof: cloneJson(proof),
+  };
+}
+
+export function toCanonicalLogUrl(url        )                  {
+  if (typeof url !== "string" || url.length === 0) {
+    throw new TypeError("log URL must be a non-empty string");
+  }
+
+  const parsed = new URL(url);
+  const path = parsed.pathname === "/" ? "/api" : parsed.pathname;
+  const protocol =
+    parsed.protocol === "http:" && isLocalHost(parsed.hostname) ? "https:" : parsed.protocol;
+  const canonical = `${protocol}//${parsed.host}${path}`;
+
+  assertCanonicalLogUrl(canonical, "logUrl");
+  return canonical;
+}
+
+function normalizeEndpoint(url        )         {
+  const parsed = new URL(url);
+  const path = parsed.pathname === "/" ? "/api" : parsed.pathname.replace(/\/$/, "");
+  return `${parsed.protocol}//${parsed.host}${path}`;
+}
+
+function buildUrl(endpoint        , path        )         {
+  return `${endpoint.replace(/\/$/, "")}${path}`;
+}
+
+function isLocalHost(hostname        )          {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+
+function isRecord(value         )                                   {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function cloneJson(value         )          {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  return globalThis.structuredClone(value);
+}

package/dist/sdk/publisher.js

@@ -0,0 +1,106 @@
+export class BackgroundReceiptPublisher {
+           #log                  ;
+           #mode            ;
+           #maxPending        ;
+           #concurrency        ;
+           #onSubmitError                           ;
+           #onDrop                             ;
+           #queue              = [];
+           #inFlight = new Set               ();
+
+  constructor(input                ) {
+    this.#log = input.log;
+    const options = normalizeSubmitOptions(input.submit);
+    this.#mode = options.mode;
+    this.#maxPending = options.maxPending;
+    this.#concurrency = options.concurrency;
+    this.#onSubmitError = input.onSubmitError;
+    this.#onDrop = input.onDrop;
+  }
+
+  get mode()             {
+    return this.#mode;
+  }
+
+  async publish(job            )                                            {
+    if (this.#mode === "await") {
+      return await this.#log.append(job.envelope, job.integratedTime);
+    }
+
+    if (this.#queue.length + this.#inFlight.size >= this.#maxPending) {
+      this.#onDrop?.({
+        envelope: new Uint8Array(job.envelope),
+        integratedTime: job.integratedTime,
+        reason: "queue_full",
+      });
+      return undefined;
+    }
+
+    const promise = new Promise                                  ((resolve, reject) => {
+      this.#queue.push({
+        envelope: new Uint8Array(job.envelope),
+        integratedTime: job.integratedTime,
+        resolve,
+        reject,
+      });
+    });
+    this.#drain();
+    return promise;
+  }
+
+  publishBackground(job            )       {
+    void this.publish(job).catch((error) => {
+      this.#onSubmitError?.(error);
+    });
+  }
+
+  async flush()                {
+    while (this.#queue.length > 0 || this.#inFlight.size > 0) {
+      await Promise.allSettled([...this.#inFlight]);
+    }
+  }
+
+  #drain()       {
+    while (this.#inFlight.size < this.#concurrency && this.#queue.length > 0) {
+      const job = this.#queue.shift()             ;
+      const task = this.#submit(job).finally(() => {
+        this.#inFlight.delete(task);
+        this.#drain();
+      });
+      this.#inFlight.add(task);
+    }
+  }
+
+  async #submit(job           )                {
+    try {
+      const entry = await this.#log.append(job.envelope, job.integratedTime);
+      job.resolve(entry);
+    } catch (error) {
+      this.#onSubmitError?.(error);
+      job.reject(error);
+    }
+  }
+}
+
+function normalizeSubmitOptions(
+  submit                                             ,
+)                               {
+  const options =
+    typeof submit === "string" || submit === undefined ? { mode: submit } : submit;
+  const mode = options.mode ?? "background";
+  if (mode !== "background" && mode !== "await") {
+    throw new TypeError("submit.mode must be background or await");
+  }
+
+  const maxPending = options.maxPending ?? 1000;
+  if (!Number.isSafeInteger(maxPending) || maxPending < 0) {
+    throw new TypeError("submit.maxPending must be a non-negative safe integer");
+  }
+
+  const concurrency = options.concurrency ?? 4;
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+    throw new TypeError("submit.concurrency must be a positive safe integer");
+  }
+
+  return { mode, maxPending, concurrency };
+}