google-photos-picker-client 0.0.0

package/README.md

@@ -0,0 +1,96 @@
+# google-photos-picker-client
+
+Framework-agnostic browser client for the
+[`google-photos-picker`](https://github.com/samrford/google-photos-picker) Go
+library's import flow: connection status, **popup-blocker-safe OAuth**, picker
+session + import polling collapsed into one state machine with an
+**exactly-once** completion, and `expired`-session handling. Optional React and
+Svelte adapters.
+
+```sh
+bun add google-photos-picker-client      # or npm / pnpm
+```
+
+## The one rule: call `connect()` / `start()` from a click
+
+Browsers only allow `window.open` during a user gesture. Each method opens
+**one** popup synchronously before any `await`, so they must be invoked
+directly from an event handler. The flow is **two gestures** when the user
+isn't connected yet — gate on `state.connected`:
+
+- falsy → `connect()` (OAuth popup)
+- `true` → `start()` (picker → import)
+
+## Core (vanilla)
+
+```ts
+import { GooglePhotosFlow, defaultEndpoints } from 'google-photos-picker-client';
+
+const flow = new GooglePhotosFlow({
+  endpoints: defaultEndpoints('/v1/google-photos'), // or hand-build Endpoints
+  postMessageType: 'myapp:google-oauth',            // === Go CallbackPage.PostMessageType
+  fetchJson: (url, init) => api(url, init),         // you inject auth + base URL; throw on non-2xx
+});
+
+flow.subscribe((s) => render(s));   // { phase, connected, progress, result, error, expired }
+await flow.refreshStatus();         // safe outside a gesture
+
+button.onclick = () =>
+  flow.state.connected ? flow.start({ /* metadata? */ }) : flow.connect();
+```
+
+`start()` resolves exactly once with `{ savedIds, total, completed, failed }`
+(also placed on `state.result`). `metadata` is only for the lib's
+client-supplied path; apps deriving the destination server-side omit it.
+
+## React
+
+```tsx
+import { useGooglePhotosFlow } from 'google-photos-picker-client/react';
+
+const cfg = useMemo(() => ({ endpoints: …, postMessageType: …, fetchJson: … }), []);
+const { state, connect, start } = useGooglePhotosFlow(cfg);
+```
+
+Status is fetched on mount, the flow cancelled on unmount. Memoise `cfg` — it's
+read once.
+
+## Svelte
+
+```svelte
+<script lang="ts">
+  import { createGooglePhotosFlow } from 'google-photos-picker-client/svelte';
+  const flow = createGooglePhotosFlow({ endpoints: …, postMessageType: …, fetchJson: … });
+  onMount(flow.refreshStatus); onDestroy(flow.cancel);
+</script>
+
+{#if $flow.phase === 'importing'}{$flow.progress?.completed}/{$flow.progress?.total}{/if}
+```
+
+`flow` is a readable store (`$flow` = state) plus `connect` / `start` /
+`disconnect` / `refreshStatus` / `cancel`. No `svelte` dependency.
+
+## Security: pin the OAuth origin in production
+
+The OAuth result is delivered to the opener via `window.postMessage`. In
+production **set `expectedOrigin`** to the origin that served the callback page
+(your API origin) so a message forged by another window can't spoof a
+successful connect — and set the Go side's `CallbackPage.TargetOrigin` to your
+frontend origin instead of the `"*"` default. Leaving both at their permissive
+defaults is acceptable for local dev only.
+
+## Config notes
+
+- **`fetchJson`** is the single HTTP seam — inject the `Authorization` header
+  and base URL here, parse JSON, **throw on non-2xx**.
+- **`postMessageType`** must equal the Go side's
+  `CallbackPage.PostMessageType`.
+- **`expectedOrigin`** — the API origin that served the callback page. Optional
+  but **strongly recommended in production** (see Security above); unset = no
+  origin check, relying solely on the Go side's `targetOrigin`.
+- **`endpoints`** are explicit because paths are the consumer's choice;
+  `defaultEndpoints(base)` covers the all-under-one-prefix case.
+
+## License
+
+MIT © Sam Ford

package/dist/chunk-ZO4U2RBX.js

@@ -0,0 +1,316 @@
+// 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.";
+}
+
+export { FlowCancelled, GooglePhotosFlow };