@synonymdev/pubky 0.6.0-rc.6 → 0.6.0-rc.7

package/package.json

@@ -2,7 +2,7 @@
   "name": "@synonymdev/pubky",
   "type": "module",
   "description": "Pubky client",
-  "version": "0.6.0-rc.6",
+  "version": "0.6.0-rc.7",
   "license": "MIT",
   "repository": {
     "type": "git",

package/pubky.d.ts

@@ -51,46 +51,40 @@ type Level = "error" | "warn" | "info" | "debug" | "trace";
  * *This API requires the following crate features to be activated: `ReadableStreamType`*
  */
 type ReadableStreamType = "bytes";
+export type Path = `/pub/${string}`;
+
+export type Address = `pubky${string}/pub/${string}` | `pubky://${string}/pub/${string}`;
+
 /**
- * Resource metadata returned by `SessionStorage.stats()` and `PublicStorage.stats()`.
- *
- * @typedef {Object} ResourceStats
- * @property {number=} contentLength  Size in bytes.
- * @property {string=} contentType    Media type (e.g. \"application/json; charset=utf-8\").
- * @property {number=} lastModifiedMs Unix epoch milliseconds.
- * @property {string=} etag           Opaque server ETag for the current version.
- *
- * @example
- * const stats = await pubky.publicStorage.stats(`${user}/pub/app/file.json`);
- * if (stats) {
- *   console.log(stats.contentLength, stats.contentType, stats.lastModifiedMs);
- * }
- *
- * Notes:
- * - `contentLength` equals `getBytes(...).length`.
- * - `etag` may be absent and is opaque; compare values to detect updates.
- * - `lastModifiedMs` increases when the resource is updated.
+ * Pkarr Config
  */
-export interface ResourceStats {
-    /**
-     * Size in bytes of the stored object.
-     */
-    contentLength?: number;
+export interface PkarrConfig {
     /**
-     * Media type of the stored object (e.g., `\"application/json\"`).
+     * The list of relays to access the DHT with.
      */
-    contentType?: string;
+    relays?: string[];
     /**
-     * Unix epoch **milliseconds** for the last modification time.
+     * The timeout for DHT requests in milliseconds.
+     * Default is 2000ms.
      */
-    lastModifiedMs?: number;
+    requestTimeout?: number;
+}
+
+/**
+ * Pubky Client Config
+ */
+export interface PubkyClientConfig {
     /**
-     * Opaque entity tag identifying the current stored version.
+     * Configuration on how to access pkarr packets on the mainline DHT.
      */
-    etag?: string;
+    pkarr?: PkarrConfig;
 }
 
-export type Path = `/pub/${string}`;
+export type CapabilityAction = "r" | "w" | "rw";
+export type CapabilityScope = `/${string}`;
+export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
+type CapabilitiesTail = `,${CapabilityEntry}${string}`;
+export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${CapabilitiesTail}`;
 
 /**
  * A union type of all possible machine-readable codes for the `name` property
@@ -168,39 +162,45 @@ export interface PubkyError extends Error {
   data?: unknown;
 }
 
-export type Address = `pubky${string}/pub/${string}` | `pubky://${string}/pub/${string}`;
-
 /**
- * Pkarr Config
+ * Resource metadata returned by `SessionStorage.stats()` and `PublicStorage.stats()`.
+ *
+ * @typedef {Object} ResourceStats
+ * @property {number=} contentLength  Size in bytes.
+ * @property {string=} contentType    Media type (e.g. \"application/json; charset=utf-8\").
+ * @property {number=} lastModifiedMs Unix epoch milliseconds.
+ * @property {string=} etag           Opaque server ETag for the current version.
+ *
+ * @example
+ * const stats = await pubky.publicStorage.stats(`${user}/pub/app/file.json`);
+ * if (stats) {
+ *   console.log(stats.contentLength, stats.contentType, stats.lastModifiedMs);
+ * }
+ *
+ * Notes:
+ * - `contentLength` equals `getBytes(...).length`.
+ * - `etag` may be absent and is opaque; compare values to detect updates.
+ * - `lastModifiedMs` increases when the resource is updated.
  */
-export interface PkarrConfig {
+export interface ResourceStats {
     /**
-     * The list of relays to access the DHT with.
+     * Size in bytes of the stored object.
      */
-    relays?: string[];
+    contentLength?: number;
     /**
-     * The timeout for DHT requests in milliseconds.
-     * Default is 2000ms.
+     * Media type of the stored object (e.g., `\"application/json\"`).
      */
-    requestTimeout?: number;
-}
-
-/**
- * Pubky Client Config
- */
-export interface PubkyClientConfig {
+    contentType?: string;
     /**
-     * Configuration on how to access pkarr packets on the mainline DHT.
+     * Unix epoch **milliseconds** for the last modification time.
      */
-    pkarr?: PkarrConfig;
+    lastModifiedMs?: number;
+    /**
+     * Opaque entity tag identifying the current stored version.
+     */
+    etag?: string;
 }
 
-export type CapabilityAction = "r" | "w" | "rw";
-export type CapabilityScope = `/${string}`;
-export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
-type CapabilitiesTail = `,${CapabilityEntry}${string}`;
-export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${CapabilitiesTail}`;
-
 /**
  * Start and control a pubkyauth authorization flow.
  *
@@ -212,6 +212,7 @@ export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${Capabilit
 export class AuthFlow {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Start a flow (standalone).
    * Prefer `pubky.startAuthFlow()` to reuse a facade client.
@@ -219,10 +220,17 @@ export class AuthFlow {
    * @param {string} capabilities
    * Comma-separated capabilities, e.g. `"/pub/app/:rw,/priv/foo.txt:r"`.
    * Each entry must be `"<scope>:<actions>"`, where:
-   * - `scope` starts with `/` (e.g. `/pub/example.app/`)
+   * - `scope` starts with `/` (e.g. `/pub/example.com/`)
    * - `actions` is any combo of `r` and/or `w` (order is normalized; `wr` -> `rw`)
    * Empty string is allowed (no scopes).
    *
+   * @param {AuthFlowKind} kind
+   * The kind of authentication flow to perform.
+   * This can either be a sign in or a sign up flow.
+   * Examples:
+   * - `AuthFlowKind.signin()` - Sign in to an existing account.
+   * - `AuthFlowKind.signup(homeserverPublicKey, signupToken)` - Sign up for a new account.
+   *
    * @param {string} [relay]
    * Optional HTTP relay base, e.g. `"https://demo.httprelay.io/link/"`.
    * Defaults to the default Synonym-hosted relay when omitted.
@@ -234,11 +242,11 @@ export class AuthFlow {
    * - `{ name: "InvalidInput", message: string }` if any capability entry is invalid
    *     or for an invalid relay URL.
    * @example
-   * const flow = AuthFlow.start("/pub/my.app/:rw,/pub/pubky.app/:w");
+   * const flow = AuthFlow.start("/pub/my-cool-app/:rw,/pub/pubky.app/:w");
    * renderQRCode(flow.authorizationUrl());
    * const session = await flow.awaitApproval();
    */
-  static start(capabilities: Capabilities, relay?: string | null): AuthFlow;
+  static start(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
   /**
    * Block until the user approves on their signer device; returns a `Session`.
    *
@@ -276,6 +284,33 @@ export class AuthFlow {
    */
   readonly authorizationUrl: string;
 }
+/**
+ * The kind of authentication flow to perform.
+ * This can either be a sign in or a sign up flow.
+ */
+export class AuthFlowKind {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Create a sign in flow.
+   */
+  static signin(): AuthFlowKind;
+  /**
+   * Create a sign up flow.
+   * # Arguments
+   * * `homeserver_public_key` - The public key of the homeserver to sign up on.
+   * * `signup_token` - The signup token to use for the signup flow. This is optional.
+   */
+  static signup(homeserver_public_key: PublicKey, signup_token?: string | null): AuthFlowKind;
+  /**
+   * Get the intent of the authentication flow.
+   * # Returns
+   * * `"signin"` - If the authentication flow is a sign in flow.
+   * * `"signup"` - If the authentication flow is a sign up flow.
+   */
+  readonly intent: string;
+}
 /**
  * AuthToken: signed, time-bound proof of key ownership.
  *
@@ -305,6 +340,7 @@ export class AuthFlow {
 export class AuthToken {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Parse and verify an `AuthToken` from its canonical bytes.
    *
@@ -361,7 +397,7 @@ export class AuthToken {
    *
    * Returns: `string[]`, where each item is the canonical entry `"<scope>:<actions>"`.
    *
-   * Example entry: `"/pub/my.app/:rw"`
+   * Example entry: `"/pub/my-cool-app/:rw"`
    */
   readonly capabilities: string[];
 }
@@ -373,18 +409,7 @@ export class AuthToken {
  */
 export class Client {
   free(): void;
-  /**
-   * Perform a raw fetch. Works with `http(s)://` URLs.
-   *
-   * @param {string} url
-   * @param {RequestInit} init Standard fetch options; `credentials: "include"` recommended for session I/O.
-   * @returns {Promise<Response>}
-   *
-   * @example
-   * const client = pubky.client;
-   * const res = await client.fetch(`https://_pubky.${user}/pub/app/file.txt`, { method: "PUT", body: "hi", credentials: "include" });
-   */
-  fetch(url: string, init?: RequestInit | null): Promise<Response>;
+  [Symbol.dispose](): void;
   /**
    * Create a Pubky HTTP client.
    *
@@ -425,10 +450,23 @@ export class Client {
    * const client = Client.testnet("docker0");  // custom host
    */
   static testnet(host?: string | null): Client;
+  /**
+   * Perform a raw fetch. Works with `http(s)://` URLs.
+   *
+   * @param {string} url
+   * @param {RequestInit} init Standard fetch options; `credentials: "include"` recommended for session I/O.
+   * @returns {Promise<Response>}
+   *
+   * @example
+   * const client = pubky.client;
+   * const res = await client.fetch(`https://_pubky.${user}/pub/app/file.txt`, { method: "PUT", body: "hi", credentials: "include" });
+   */
+  fetch(url: string, init?: RequestInit | null): Promise<Response>;
 }
 export class IntoUnderlyingByteSource {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   start(controller: ReadableByteStreamController): void;
   pull(controller: ReadableByteStreamController): Promise<any>;
   cancel(): void;
@@ -438,6 +476,7 @@ export class IntoUnderlyingByteSource {
 export class IntoUnderlyingSink {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   write(chunk: any): Promise<any>;
   close(): Promise<any>;
   abort(reason: any): Promise<any>;
@@ -445,12 +484,14 @@ export class IntoUnderlyingSink {
 export class IntoUnderlyingSource {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   pull(controller: ReadableStreamDefaultController): Promise<any>;
   cancel(): void;
 }
 export class Keypair {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Generate a random [Keypair]
    */
@@ -486,6 +527,7 @@ export class Keypair {
  */
 export class Pkdns {
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Read-only PKDNS actor (no keypair; resolve only).
    */
@@ -531,6 +573,7 @@ export class Pkdns {
  */
 export class Pubky {
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Create a Pubky facade wired for **mainnet** defaults (public relays).
    *
@@ -573,11 +616,15 @@ export class Pubky {
    * Provide a **capabilities string** and (optionally) a relay base URL.
    * The capabilities string is a comma-separated list of entries:
    * `"<scope>:<actions>"`, where:
-   * - `scope` starts with `/` (e.g. `/pub/example.app/`).
+   * - `scope` starts with `/` (e.g. `/pub/example.com/`).
    * - `actions` is any combo of `r` and/or `w` (order normalized; `wr` -> `rw`).
    * Pass `""` for no scopes (read-only public session).
    *
    * @param {string} capabilities Comma-separated caps, e.g. `"/pub/app/:rw,/pub/foo/file:r"`.
+   * @param {AuthFlowKind} kind The kind of authentication flow to perform.
+   * Examples:
+   * - `AuthFlowKind.signin()` - Sign in to an existing account.
+   * - `AuthFlowKind.signup(homeserverPublicKey, signupToken)` - Sign up for a new account.
    * @param {string=} relay Optional HTTP relay base (e.g. `"https://…/link/"`).
    * @returns {AuthFlow}
    * A running auth flow. Show `authorizationUrl` as QR/deeplink,
@@ -588,11 +635,11 @@ export class Pubky {
    * - `{ name: "RequestError" }` if the flow cannot be started (network/relay)
    *
    * @example
-   * const flow = pubky.startAuthFlow("/pub/my.app/:rw");
+   * const flow = pubky.startAuthFlow("/pub/my-cool-app/:rw");
    * renderQr(flow.authorizationUrl);
    * const session = await flow.awaitApproval();
    */
-  startAuthFlow(capabilities: Capabilities, relay?: string | null): AuthFlow;
+  startAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null): AuthFlow;
   /**
    * Create a `Signer` from an existing `Keypair`.
    *
@@ -613,6 +660,20 @@ export class Pubky {
    * @returns {Promise<PublicKey|undefined>} Homeserver public key (z32) or `undefined` if not found.
    */
   getHomeserverOf(user_public_key: PublicKey): Promise<PublicKey | undefined>;
+  /**
+   * Restore a session from a previously exported snapshot, using this instance's client.
+   *
+   * This does **not** read or write any secrets. It revalidates the session metadata with
+   * the server using the browser-managed HTTP-only cookie that must still be present.
+   *
+   * @param {string} exported A string produced by `session.export()`.
+   * @returns {Promise<Session>}
+   * A rehydrated session bound to this SDK's HTTP client.
+   *
+   * @example
+   * const restored = await pubky.restoreSession(localStorage.getItem("pubky-session")!);
+   */
+  restoreSession(exported: string): Promise<Session>;
   /**
    * Public, unauthenticated storage API.
    *
@@ -639,6 +700,7 @@ export class Pubky {
 export class PublicKey {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Convert the PublicKey to Uint8Array
    */
@@ -657,6 +719,7 @@ export class PublicKey {
  */
 export class PublicStorage {
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Construct PublicStorage using global client (mainline relays).
    */
@@ -716,6 +779,14 @@ export class PublicStorage {
    */
   stats(address: Address): Promise<ResourceStats | undefined>;
 }
+export class SeedExportDeepLink {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static parse(url: string): SeedExportDeepLink;
+  toString(): string;
+  readonly secret: Uint8Array;
+}
 /**
  * An authenticated context “as the user”.
  * - Use `storage` for reads/writes (absolute paths like `/pub/app/file.txt`)
@@ -724,6 +795,7 @@ export class PublicStorage {
 export class Session {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Invalidate the session on the server (clears server cookie).
    * Further calls to storage API will fail.
@@ -731,6 +803,29 @@ export class Session {
    * @returns {Promise<void>}
    */
   signout(): Promise<void>;
+  /**
+   * Export the session metadata so it can be restored after a tab refresh.
+   *
+   * The export string contains **no secrets**; it only serializes the public `SessionInfo`.
+   * Browsers remain responsible for persisting the HTTP-only session cookie.
+   *
+   * @returns {string}
+   * A base64 string to store (e.g. in `localStorage`).
+   */
+  export(): string;
+  /**
+   * Restore a session from an `export()` string.
+   *
+   * The HTTP-only cookie must still be present in the browser; this function does not
+   * read or write any secrets.
+   *
+   * @param {string} exported
+   * A string produced by `session.export()`.
+   * @param {Client=} client
+   * Optional client to reuse transport configuration.
+   * @returns {Promise<Session>}
+   */
+  static restore(exported: string, client?: Client | null): Promise<Session>;
   /**
    * Retrieve immutable info about this session (user & capabilities).
    *
@@ -750,6 +845,7 @@ export class Session {
 export class SessionInfo {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * The user’s public key for this session.
    *
@@ -774,6 +870,7 @@ export class SessionInfo {
 export class SessionStorage {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * List a directory (absolute session path). Returns `pubky://…` URLs.
    *
@@ -870,6 +967,7 @@ export class SessionStorage {
 export class Signer {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
    * Create a signer from a `Keypair` (prefer `pubky.signer(kp)`).
    *
@@ -929,3 +1027,25 @@ export class Signer {
    */
   readonly pkdns: Pkdns;
 }
+export class SigninDeepLink {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static parse(url: string): SigninDeepLink;
+  toString(): string;
+  readonly capabilities: string;
+  readonly baseRelayUrl: string;
+  readonly secret: Uint8Array;
+}
+export class SignupDeepLink {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  static parse(url: string): SignupDeepLink;
+  toString(): string;
+  readonly capabilities: string;
+  readonly baseRelayUrl: string;
+  readonly secret: Uint8Array;
+  readonly homeserver: PublicKey;
+  readonly signupToken: string | undefined;
+}