@synonymdev/pubky 0.7.0 → 0.8.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@synonymdev/pubky",
   "type": "module",
   "description": "Pubky client",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/pubky.d.ts

@@ -196,6 +196,22 @@ export class AuthFlow {
      * - `RequestError` if relay/network fails
      */
     awaitToken(): Promise<AuthToken>;
+    /**
+     * Resume a previously started auth flow from its saved `authorizationUrl` (standalone).
+     * Prefer `pubky.resumeAuthFlow()` to reuse a facade client; this creates a default (mainnet) client.
+     *
+     * Relay messages expire after ~5 minutes; resume is only viable in that window.
+     * See `Pubky.resumeAuthFlow()` / `Pubky.startAuthFlow()` for full guidance.
+     *
+     * **Security:** `authorizationUrl` contains the `client_secret`.
+     * Delete it from storage as soon as resume completes or is abandoned.
+     *
+     * @param {string} authorizationUrl The `pubkyauth://…` URL from a previous flow.
+     * @returns {AuthFlow} A flow reconnected to the original relay channel.
+     * @throws {PubkyError}
+     * - `{ name: "AuthenticationError" }` if the URL is invalid or not a signin/signup link
+     */
+    static resume(authorization_url: string): AuthFlow;
     /**
      * Start a flow (standalone).
      * Prefer `pubky.startAuthFlow()` to reuse a facade client.
@@ -239,10 +255,14 @@ export class AuthFlow {
     /**
      * Return the authorization deep link (URL) to show as QR or open on the signer device.
      *
+     * **Security:** This URL contains the `client_secret` in plaintext.
+     * Treat it as a short-lived secret and delete it after the flow completes.
+     * See `Pubky.startAuthFlow()` docs for storage guidance.
+     *
      * @returns {string} A `pubkyauth://…` or `https://…` URL with channel info.
      *
      * @example
-     * renderQr(flow.authorizationUrl());
+     * renderQr(flow.authorizationUrl);
      */
     readonly authorizationUrl: string;
 }
@@ -809,6 +829,23 @@ export class Pubky {
      * const restored = await pubky.restoreSession(localStorage.getItem("pubky-session")!);
      */
     restoreSession(exported: string): Promise<Session>;
+    /**
+     * Resume a previously started **pubkyauth** flow from its saved `authorizationUrl`.
+     *
+     * The relay inbox retains messages for **~5 minutes**. Resume is only
+     * viable within that window; afterwards start a fresh flow.
+     *
+     * **Security:** The URL contains the `client_secret` in plaintext.
+     * Delete it from storage as soon as the resumed flow completes.
+     * See `startAuthFlow()` docs for full storage guidance.
+     *
+     * @param {string} authorizationUrl The `pubkyauth://…` URL from a previous flow.
+     * @returns {AuthFlow} A flow reconnected to the original relay channel.
+     * @throws {PubkyError}
+     * - `{ name: "AuthenticationError" }` if the URL is invalid or not a signin/signup link
+     * - `{ name: "RequestError" }` on network/relay failure
+     */
+    resumeAuthFlow(authorization_url: string): AuthFlow;
     /**
      * Create a `Signer` from an existing `Keypair`.
      *
@@ -830,6 +867,10 @@ export class Pubky {
      * - `actions` is any combo of `r` and/or `w` (order normalized; `wr` -> `rw`).
      * Pass `""` for no scopes (read-only public session).
      *
+     * **Security:** `authorizationUrl` contains the `client_secret` in plaintext.
+     * If you need resume after refresh/app switch, save it in `sessionStorage`
+     * (not `localStorage`), then delete it once approval arrives or is abandoned.
+     *
      * @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: