google-photos-picker-client 0.0.0

package/dist/index.cjs

@@ -0,0 +1,335 @@
+'use strict';
+
+// src/flow.ts
+var FlowCancelled = class extends Error {
+  constructor() {
+    super("google-photos flow cancelled");
+    this.name = "FlowCancelled";
+  }
+};
+var DEFAULT_SESSION_POLL_MS = 2e3;
+var DEFAULT_JOB_POLL_MS = 1500;
+var MAX_POLL_FAILURES = 4;
+var MAX_POLL_BACKOFF_MS = 15e3;
+var OAUTH_TIMEOUT_MS = 5 * 60 * 1e3;
+var INITIAL = {
+  phase: "idle",
+  connected: null,
+  progress: null,
+  result: null,
+  error: null,
+  expired: false
+};
+var GooglePhotosFlow = class {
+  constructor(config) {
+    this._state = INITIAL;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.waiters = /* @__PURE__ */ new Set();
+    this.popup = null;
+    /** Bumped by cancel() and by each new run; stale loops detect this and bail. */
+    this.runId = 0;
+    this.config = config;
+  }
+  get state() {
+    return this._state;
+  }
+  /** Register a state listener. Does not emit the current value (framework
+   *  adapters surface the initial value themselves). Returns an unsubscribe. */
+  subscribe(fn) {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+  setState(patch) {
+    this._state = { ...this._state, ...patch };
+    for (const fn of this.listeners) fn(this._state);
+  }
+  /** Abort any in-flight run, close popups, reset to idle (unless terminal). */
+  cancel() {
+    this.runId++;
+    this.clearTimers();
+    this.closePopup();
+    if (this._state.phase !== "done" && this._state.phase !== "error") {
+      this.setState({ phase: "idle", progress: null });
+    }
+  }
+  clearTimers() {
+    for (const w of this.waiters) {
+      clearTimeout(w.timer);
+      w.reject(new FlowCancelled());
+    }
+    this.waiters.clear();
+  }
+  closePopup() {
+    const p = this.popup;
+    this.popup = null;
+    if (p && !p.closed) {
+      try {
+        p.close();
+      } catch {
+      }
+    }
+  }
+  /** Fetch connection status. Safe to call on mount (not a user gesture). */
+  async refreshStatus() {
+    try {
+      const s = await this.config.fetchJson(this.config.endpoints.status);
+      this.setState({ connected: !!s.connected, error: null });
+    } catch {
+      this.setState({ connected: false });
+    }
+  }
+  /** Revoke the Google connection. */
+  async disconnect() {
+    try {
+      await this.config.fetchJson(this.config.endpoints.disconnect, { method: "DELETE" });
+      this.setState({ connected: false, error: null });
+    } catch (e) {
+      this.setState({ error: messageOf(e) });
+      throw e;
+    }
+  }
+  /**
+   * Run the OAuth dance. MUST be called from a user-gesture handler: a blank
+   * popup is opened synchronously, then pointed at the consent URL once the
+   * backend returns it, then resolved/rejected from the callback postMessage.
+   */
+  async connect() {
+    const win = this.openBlank("gpp-oauth");
+    const myRun = ++this.runId;
+    this.setState({ phase: "connecting", error: null, expired: false });
+    try {
+      if (!win) throw new Error("Popup blocked \u2014 allow popups and retry.");
+      this.popup = win;
+      const { consentUrl } = await this.config.fetchJson(
+        this.config.endpoints.connect
+      );
+      this.ensureCurrent(myRun);
+      if (win.closed) throw new Error("Authorisation window was closed.");
+      win.location.href = consentUrl;
+      await this.waitForOAuth(myRun);
+      this.closePopup();
+      this.setState({ phase: "idle", connected: true });
+    } catch (e) {
+      this.closePopup();
+      this.handleError(e, myRun);
+      throw e;
+    }
+  }
+  /**
+   * Run create-session → pick → import to completion. MUST be called from a
+   * user-gesture handler and only when `state.connected` is true (the UI
+   * gates this; if called disconnected it errors fast). Resolves exactly once
+   * with the final result; the same result is also placed on `state.result`.
+   */
+  async start(opts = {}) {
+    const myRun = ++this.runId;
+    try {
+      if (this._state.connected === false) {
+        throw new Error("Not connected to Google Photos \u2014 connect first.");
+      }
+      const win = this.openBlank("gpp-picker");
+      this.setState({
+        phase: "creating",
+        error: null,
+        expired: false,
+        result: null,
+        progress: null
+      });
+      if (!win) throw new Error("Popup blocked \u2014 allow popups and retry.");
+      this.popup = win;
+      const session = await this.config.fetchJson(
+        this.config.endpoints.createSession,
+        { method: "POST" }
+      );
+      this.ensureCurrent(myRun);
+      if (win.closed) throw new Error("Picker window was closed.");
+      win.location.href = session.pickerUri;
+      this.setState({ phase: "picking" });
+      await this.pollSession(session.sessionId, myRun);
+      this.closePopup();
+      this.setState({ phase: "importing" });
+      const { importJobId } = await this.config.fetchJson(
+        this.config.endpoints.startImport(session.sessionId),
+        opts.metadata ? {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ metadata: opts.metadata })
+        } : { method: "POST" }
+      );
+      this.ensureCurrent(myRun);
+      const result = await this.pollJob(importJobId, myRun);
+      this.setState({ phase: "done", result });
+      return result;
+    } catch (e) {
+      this.closePopup();
+      this.handleError(e, myRun);
+      throw e;
+    }
+  }
+  // ─── internals ────────────────────────────────────────────────────────────
+  openBlank(name) {
+    const open = this.config.openWindow ?? ((u, n) => window.open(u, n));
+    return open("about:blank", name);
+  }
+  ensureCurrent(myRun) {
+    if (this.runId !== myRun) throw new FlowCancelled();
+  }
+  // Resolves after `ms`, unless the run is superseded/cancelled first - then it
+  // rejects with FlowCancelled. Registered in `waiters` so clearTimers() can
+  // interrupt an in-flight wait, which makes it abortable on demand.
+  cancellableDelay(ms, myRun) {
+    return new Promise((resolve, reject) => {
+      const w = {
+        timer: setTimeout(() => {
+          this.waiters.delete(w);
+          this.runId === myRun ? resolve() : reject(new FlowCancelled());
+        }, ms),
+        reject
+      };
+      this.waiters.add(w);
+    });
+  }
+  // Polling fetch with retry + exponential backoff.
+  // FlowCancelled and cancellation always propagate at once.
+  async pollFetch(url, myRun, baseMs) {
+    let failures = 0;
+    for (; ; ) {
+      try {
+        return await this.config.fetchJson(url);
+      } catch (e) {
+        if (e instanceof FlowCancelled) throw e;
+        this.ensureCurrent(myRun);
+        if (++failures > MAX_POLL_FAILURES) throw e;
+        await this.cancellableDelay(Math.min(baseMs * 2 ** (failures - 1), MAX_POLL_BACKOFF_MS), myRun);
+      }
+    }
+  }
+  async pollSession(sessionId, myRun) {
+    const interval = this.config.pollIntervalMs?.session ?? DEFAULT_SESSION_POLL_MS;
+    for (; ; ) {
+      const s = await this.pollFetch(
+        this.config.endpoints.pollSession(sessionId),
+        myRun,
+        interval
+      );
+      this.ensureCurrent(myRun);
+      if (s.status === "ready") return;
+      if (s.status === "expired") {
+        const err = new Error("The Google Photos session expired before you confirmed a selection.");
+        err.expired = true;
+        throw err;
+      }
+      await this.cancellableDelay(interval, myRun);
+    }
+  }
+  async pollJob(jobId, myRun) {
+    const interval = this.config.pollIntervalMs?.job ?? DEFAULT_JOB_POLL_MS;
+    for (; ; ) {
+      const job = await this.pollFetch(
+        this.config.endpoints.getImport(jobId),
+        myRun,
+        interval
+      );
+      this.ensureCurrent(myRun);
+      this.setState({
+        progress: { total: job.total, completed: job.completed, failed: job.failed }
+      });
+      if (job.status === "complete") {
+        return {
+          savedIds: job.savedIds ?? [],
+          total: job.total,
+          completed: job.completed,
+          failed: job.failed
+        };
+      }
+      if (job.status === "failed") {
+        throw new Error(job.error || "Import failed.");
+      }
+      await this.cancellableDelay(interval, myRun);
+    }
+  }
+  // Resolves once the Go callback page (loaded in the popup after Google's
+  // redirect) posts `{ type, status, message }` back via window.opener.
+  // Settles exactly once — the matching postMessage (success → resolve, error
+  // → reject with its message), the run being superseded (→ FlowCancelled), or
+  // an overall timeout. The timeout is the backstop for if the
+  // user abandons consent. Non-matching messages (wrong type, or wrong origin
+  // when `expectedOrigin` is set) are ignored, not rejected — other
+  // postMessages on the page must pass through untouched.
+  waitForOAuth(myRun) {
+    const target = this.config.messageTarget ?? globalThis;
+    const expectedOrigin = this.config.expectedOrigin;
+    const type = this.config.postMessageType;
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        clearInterval(poll);
+        clearTimeout(timeout);
+        target.removeEventListener("message", onMessage);
+      };
+      const onMessage = (e) => {
+        if (this.runId !== myRun) {
+          finish();
+          reject(new FlowCancelled());
+          return;
+        }
+        if (expectedOrigin !== void 0 && e.origin !== expectedOrigin) return;
+        const d = e.data;
+        if (!d || typeof d !== "object" || d.type !== type) return;
+        finish();
+        if (d.status === "success") resolve();
+        else reject(new Error(typeof d.message === "string" && d.message ? d.message : "Google authorisation failed."));
+      };
+      const poll = setInterval(() => {
+        if (this.runId !== myRun) {
+          finish();
+          reject(new FlowCancelled());
+        }
+      }, 500);
+      const timeout = setTimeout(() => {
+        finish();
+        reject(new Error("Google authorisation timed out \u2014 please try again."));
+      }, OAUTH_TIMEOUT_MS);
+      target.addEventListener("message", onMessage);
+    });
+  }
+  handleError(e, myRun) {
+    if (e instanceof FlowCancelled || this.runId !== myRun) {
+      return;
+    }
+    this.setState({
+      phase: "error",
+      error: messageOf(e),
+      expired: isExpired(e)
+    });
+  }
+};
+function isExpired(e) {
+  return !!(e && typeof e === "object" && e.expired === true);
+}
+function messageOf(e) {
+  if (e instanceof Error) return e.message;
+  if (typeof e === "string") return e;
+  return "Something went wrong.";
+}
+
+// src/endpoints.ts
+function defaultEndpoints(base) {
+  const b = base.replace(/\/$/, "");
+  const enc = encodeURIComponent;
+  return {
+    status: `${b}/status`,
+    connect: `${b}/connect`,
+    disconnect: `${b}/disconnect`,
+    createSession: `${b}/sessions`,
+    pollSession: (id) => `${b}/sessions/${enc(id)}`,
+    startImport: (id) => `${b}/sessions/${enc(id)}/import`,
+    getImport: (id) => `${b}/imports/${enc(id)}`
+  };
+}
+
+exports.FlowCancelled = FlowCancelled;
+exports.GooglePhotosFlow = GooglePhotosFlow;
+exports.defaultEndpoints = defaultEndpoints;

package/dist/index.d.cts

@@ -0,0 +1,84 @@
+import { F as FlowConfig, c as FlowState, g as StartOptions, C as CompleteResult, E as Endpoints } from './types-BUF5FPLM.cjs';
+export { a as CreateSessionResponse, b as FlowPhase, G as GoogleStatus, I as ImportJob, d as ImportJobStatus, e as ImportProgress, S as SessionStatus, f as StartImportResponse } from './types-BUF5FPLM.cjs';
+
+/** Thrown internally when a run is superseded or cancelled. Not surfaced as a
+ *  flow error — the state simply returns to idle. */
+declare class FlowCancelled extends Error {
+    constructor();
+}
+/**
+ * GooglePhotosFlow drives the entire import flow framework-agnostically:
+ * status, popup-safe OAuth, picker session, both poll loops, and an
+ * exactly-once completion. It owns its timers and emits state changes to
+ * subscribers; framework adapters are thin wrappers over `subscribe` + the
+ * action methods.
+ *
+ * Popup-blocker safety: `connect()` and `start()` each open exactly one window
+ * synchronously, before any `await` and before the first `setState()` (only a
+ * cheap synchronous precheck may precede it), so they must be called from a
+ * user-gesture handler. They never open a second window after an await (the
+ * fragile pattern). If the user isn't connected, the UI flow is two
+ * gestures: click → connect(), then click → start().
+ */
+declare class GooglePhotosFlow {
+    private readonly config;
+    private _state;
+    private readonly listeners;
+    private readonly waiters;
+    private popup;
+    /** Bumped by cancel() and by each new run; stale loops detect this and bail. */
+    private runId;
+    constructor(config: FlowConfig);
+    get state(): FlowState;
+    /** Register a state listener. Does not emit the current value (framework
+     *  adapters surface the initial value themselves). Returns an unsubscribe. */
+    subscribe(fn: (s: FlowState) => void): () => void;
+    private setState;
+    /** Abort any in-flight run, close popups, reset to idle (unless terminal). */
+    cancel(): void;
+    private clearTimers;
+    private closePopup;
+    /** Fetch connection status. Safe to call on mount (not a user gesture). */
+    refreshStatus(): Promise<void>;
+    /** Revoke the Google connection. */
+    disconnect(): Promise<void>;
+    /**
+     * Run the OAuth dance. MUST be called from a user-gesture handler: a blank
+     * popup is opened synchronously, then pointed at the consent URL once the
+     * backend returns it, then resolved/rejected from the callback postMessage.
+     */
+    connect(): Promise<void>;
+    /**
+     * Run create-session → pick → import to completion. MUST be called from a
+     * user-gesture handler and only when `state.connected` is true (the UI
+     * gates this; if called disconnected it errors fast). Resolves exactly once
+     * with the final result; the same result is also placed on `state.result`.
+     */
+    start(opts?: StartOptions): Promise<CompleteResult>;
+    private openBlank;
+    private ensureCurrent;
+    private cancellableDelay;
+    private pollFetch;
+    private pollSession;
+    private pollJob;
+    private waitForOAuth;
+    private handleError;
+}
+
+/**
+ * Conventional endpoint layout for the common case: all routes under a single
+ * base path. Consumers whose routes diverge (e.g. status/connect under a
+ * different prefix) build the `Endpoints` object by hand instead.
+ *
+ *   defaultEndpoints('/v1/google-photos')
+ *     → POST   /v1/google-photos/sessions
+ *       GET    /v1/google-photos/sessions/:id
+ *       POST   /v1/google-photos/sessions/:id/import
+ *       GET    /v1/google-photos/imports/:id
+ *       GET    /v1/google-photos/status
+ *       GET    /v1/google-photos/connect
+ *       DELETE /v1/google-photos/disconnect
+ */
+declare function defaultEndpoints(base: string): Endpoints;
+
+export { CompleteResult, Endpoints, FlowCancelled, FlowConfig, FlowState, GooglePhotosFlow, StartOptions, defaultEndpoints };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import { F as FlowConfig, c as FlowState, g as StartOptions, C as CompleteResult, E as Endpoints } from './types-BUF5FPLM.js';
+export { a as CreateSessionResponse, b as FlowPhase, G as GoogleStatus, I as ImportJob, d as ImportJobStatus, e as ImportProgress, S as SessionStatus, f as StartImportResponse } from './types-BUF5FPLM.js';
+
+/** Thrown internally when a run is superseded or cancelled. Not surfaced as a
+ *  flow error — the state simply returns to idle. */
+declare class FlowCancelled extends Error {
+    constructor();
+}
+/**
+ * GooglePhotosFlow drives the entire import flow framework-agnostically:
+ * status, popup-safe OAuth, picker session, both poll loops, and an
+ * exactly-once completion. It owns its timers and emits state changes to
+ * subscribers; framework adapters are thin wrappers over `subscribe` + the
+ * action methods.
+ *
+ * Popup-blocker safety: `connect()` and `start()` each open exactly one window
+ * synchronously, before any `await` and before the first `setState()` (only a
+ * cheap synchronous precheck may precede it), so they must be called from a
+ * user-gesture handler. They never open a second window after an await (the
+ * fragile pattern). If the user isn't connected, the UI flow is two
+ * gestures: click → connect(), then click → start().
+ */
+declare class GooglePhotosFlow {
+    private readonly config;
+    private _state;
+    private readonly listeners;
+    private readonly waiters;
+    private popup;
+    /** Bumped by cancel() and by each new run; stale loops detect this and bail. */
+    private runId;
+    constructor(config: FlowConfig);
+    get state(): FlowState;
+    /** Register a state listener. Does not emit the current value (framework
+     *  adapters surface the initial value themselves). Returns an unsubscribe. */
+    subscribe(fn: (s: FlowState) => void): () => void;
+    private setState;
+    /** Abort any in-flight run, close popups, reset to idle (unless terminal). */
+    cancel(): void;
+    private clearTimers;
+    private closePopup;
+    /** Fetch connection status. Safe to call on mount (not a user gesture). */
+    refreshStatus(): Promise<void>;
+    /** Revoke the Google connection. */
+    disconnect(): Promise<void>;
+    /**
+     * Run the OAuth dance. MUST be called from a user-gesture handler: a blank
+     * popup is opened synchronously, then pointed at the consent URL once the
+     * backend returns it, then resolved/rejected from the callback postMessage.
+     */
+    connect(): Promise<void>;
+    /**
+     * Run create-session → pick → import to completion. MUST be called from a
+     * user-gesture handler and only when `state.connected` is true (the UI
+     * gates this; if called disconnected it errors fast). Resolves exactly once
+     * with the final result; the same result is also placed on `state.result`.
+     */
+    start(opts?: StartOptions): Promise<CompleteResult>;
+    private openBlank;
+    private ensureCurrent;
+    private cancellableDelay;
+    private pollFetch;
+    private pollSession;
+    private pollJob;
+    private waitForOAuth;
+    private handleError;
+}
+
+/**
+ * Conventional endpoint layout for the common case: all routes under a single
+ * base path. Consumers whose routes diverge (e.g. status/connect under a
+ * different prefix) build the `Endpoints` object by hand instead.
+ *
+ *   defaultEndpoints('/v1/google-photos')
+ *     → POST   /v1/google-photos/sessions
+ *       GET    /v1/google-photos/sessions/:id
+ *       POST   /v1/google-photos/sessions/:id/import
+ *       GET    /v1/google-photos/imports/:id
+ *       GET    /v1/google-photos/status
+ *       GET    /v1/google-photos/connect
+ *       DELETE /v1/google-photos/disconnect
+ */
+declare function defaultEndpoints(base: string): Endpoints;
+
+export { CompleteResult, Endpoints, FlowCancelled, FlowConfig, FlowState, GooglePhotosFlow, StartOptions, defaultEndpoints };

package/dist/index.js

@@ -0,0 +1,18 @@
+export { FlowCancelled, GooglePhotosFlow } from './chunk-ZO4U2RBX.js';
+
+// src/endpoints.ts
+function defaultEndpoints(base) {
+  const b = base.replace(/\/$/, "");
+  const enc = encodeURIComponent;
+  return {
+    status: `${b}/status`,
+    connect: `${b}/connect`,
+    disconnect: `${b}/disconnect`,
+    createSession: `${b}/sessions`,
+    pollSession: (id) => `${b}/sessions/${enc(id)}`,
+    startImport: (id) => `${b}/sessions/${enc(id)}/import`,
+    getImport: (id) => `${b}/imports/${enc(id)}`
+  };
+}
+
+export { defaultEndpoints };