@pawabase/client 0.0.0-stage → 0.1.0

package/dist/esm/util.js

@@ -0,0 +1,102 @@
+import { AbortError } from "./errors.js";
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Sleep for `ms`, rejecting early with {@link AbortError} when `signal` fires. */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(new AbortError(undefined, { cause: signal.reason }));
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new AbortError(undefined, { cause: signal?.reason }));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Exponential backoff with full jitter: a random delay in `[0, min(max, base * factor^attempt)]`. */
+export function backoff(attempt, options, random = Math.random) {
+    const ceiling = Math.min(options.maxDelayMs, options.baseDelayMs * (options.factor ?? 2) ** attempt);
+    return Math.floor(random() * ceiling);
+}
+/** One signal that fires when any of `signals` fires. Uses the platform's `AbortSignal.any` when present. */
+export function anySignal(signals) {
+    const real = signals.filter((s) => !!s);
+    if (real.length === 0)
+        return undefined;
+    if (real.length === 1)
+        return real[0];
+    const native = AbortSignal.any;
+    if (native)
+        return native(real);
+    const controller = new AbortController();
+    for (const signal of real) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+    }
+    return controller.signal;
+}
+/** `a/b c/d` to `a/b%20c/d`: encode each path segment, keep the slashes. */
+export function encodePath(path) {
+    return path
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+/** A query string from a flat record. Drops `undefined`/`null`; arrays repeat the key. */
+export function queryString(params) {
+    if (!params)
+        return "";
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        const items = Array.isArray(value) ? value : [value];
+        for (const item of items) {
+            if (item === undefined || item === null)
+                continue;
+            search.append(key, item instanceof Date ? item.toISOString() : String(item));
+        }
+    }
+    const text = search.toString();
+    return text ? `?${text}` : "";
+}
+export function trimSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+export function randomId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+/** Decode a JWT payload without verifying it (the server verifies). Returns `null` for malformed tokens. */
+export function decodeJwt(token) {
+    const part = token.split(".")[1];
+    if (!part)
+        return null;
+    try {
+        const base64 = part.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(part.length / 4) * 4, "=");
+        const text = typeof atob === "function"
+            ? decodeURIComponent(Array.from(atob(base64), (ch) => "%" + ch.charCodeAt(0).toString(16).padStart(2, "0")).join(""))
+            : globalThis.Buffer.from(base64, "base64").toString("utf8");
+        const value = JSON.parse(text);
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a key is a secret key (`pb_sk_…`, or `sk_…` in older docs). */
+export function isSecretKey(apiKey) {
+    return /^(pb_)?sk_/.test(apiKey);
+}
+//# sourceMappingURL=util.js.map

package/dist/esm/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../../src/util.ts"],"names":[],"mappings":"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"}

package/dist/esm/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/esm/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/esm/version.js

@@ -0,0 +1,2 @@
+export const VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/esm/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@pawabase/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Official TypeScript client for Pawabase: data, auth, storage, functions, flows and realtime.",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./manage": {
+      "import": {
+        "types": "./dist/esm/manage/index.d.ts",
+        "default": "./dist/esm/manage/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/manage/index.d.ts",
+        "default": "./dist/cjs/manage/index.js"
+      }
+    },
+    "./admin": {
+      "import": {
+        "types": "./dist/esm/admin.d.ts",
+        "default": "./dist/esm/admin.js"
+      },
+      "require": {
+        "types": "./dist/cjs/admin.d.ts",
+        "default": "./dist/cjs/admin.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "pawabase-types": "./dist/esm/cli/gen-types.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/finish-build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "rm -rf dist-test && tsc -p tsconfig.test.json && node --test --test-concurrency=1 $(find dist-test/test -name \"*.test.js\")",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "pawabase",
+    "backend",
+    "sdk",
+    "realtime",
+    "auth",
+    "storage"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.2",
+    "typescript": "^5.6.0",
+    "ws": "^8.22.0"
+  },
+  "typesVersions": {
+    "*": {
+      "manage": [
+        "./dist/esm/manage/index.d.ts"
+      ],
+      "admin": [
+        "./dist/esm/admin.d.ts"
+      ]
+    }
+  }
+}

package/src/admin.ts

@@ -0,0 +1,311 @@
+/**
+ * Administer the environment's users, organizations and roles, with the environment's secret key (`pb_sk_…`).
+ *
+ * These are the people who sign in to *your* application, not the project's own team. Every call is scoped to one environment;
+ * a user of one environment is never visible in another.
+ *
+ * ```ts
+ * import { createClient } from "@pawabase/client";
+ * import { admin } from "@pawabase/client/admin";
+ *
+ * const a = admin(createClient({ url, apiKey: "pb_sk_…", environment: "production" }));
+ * await a.users.create({ email: "ada@example.com", password: "…", roles: ["editor"] });
+ * await a.users.update(userId, { disabled: true });
+ * await a.orgs.addMember("acme", { email: "ada@example.com", role: "admin" });
+ * ```
+ */
+import type { PawabaseClient } from "./client.js";
+import { ConfigError } from "./errors.js";
+import type { HttpClient } from "./http.js";
+import { Service, seg, type Api, type Body } from "./manage/base.js";
+import { isSecretKey } from "./util.js";
+
+class AdminService extends Service {
+  protected override path(suffix = ""): string {
+    return `/platform/v1/envs/${encodeURIComponent(this.environment)}/auth${suffix}`;
+  }
+}
+
+export interface NewUser {
+  email: string;
+  password?: string;
+  username?: string;
+  name?: string;
+  /** Default `true`: an operator vouches for the address. */
+  emailVerified?: boolean;
+  /** Visible to the user and editable by them. */
+  userMetadata?: Body;
+  /** Visible to your server only. */
+  appMetadata?: Body;
+  roles?: string[];
+}
+
+export interface UserChanges {
+  name?: string;
+  emailVerified?: boolean;
+  /** Blocks sign-in and ends the user's sessions. */
+  disabled?: boolean;
+  password?: string;
+  userMetadata?: Body;
+  appMetadata?: Body;
+  /** Replaces the user's roles. */
+  roles?: string[];
+  /** Clears a lockout after failed sign-ins. */
+  unlock?: boolean;
+}
+
+export class Users extends AdminService {
+  /** `search` matches email, username and name. `status`: `disabled`, `unverified`, `locked`, `mfa`, `no_mfa`. */
+  search(options: { search?: string; status?: string; limit?: number; offset?: number } = {}): Promise<Api> {
+    return this.get("/users", { limit: 50, offset: 0, ...options });
+  }
+
+  getUser(userId: string): Promise<Api> {
+    return this.get(seg("users", userId));
+  }
+
+  /** Create an account without the sign-up restrictions (allow-lists; the password policy still applies). */
+  create(user: NewUser): Promise<Api> {
+    return this.post("/users", {
+      email: user.email,
+      password: user.password,
+      username: user.username,
+      name: user.name ?? "",
+      email_verified: user.emailVerified ?? true,
+      user_metadata: user.userMetadata ?? {},
+      app_metadata: user.appMetadata ?? {},
+      roles: user.roles ?? [],
+    });
+  }
+
+  update(userId: string, changes: UserChanges): Promise<Api> {
+    return this.patch(seg("users", userId), {
+      name: changes.name,
+      email_verified: changes.emailVerified,
+      disabled: changes.disabled,
+      password: changes.password,
+      user_metadata: changes.userMetadata,
+      app_metadata: changes.appMetadata,
+      roles: changes.roles,
+      unlock: changes.unlock,
+    });
+  }
+
+  deleteUser(userId: string): Promise<Api> {
+    return this.del(seg("users", userId));
+  }
+
+  /** The user's recent sign-ins and security events. */
+  history(userId: string): Promise<Api> {
+    return this.get(seg("users", userId, "history"));
+  }
+
+  /** Remove the user's second factors, so they can sign in with a password alone and enrol again. */
+  resetMfa(userId: string): Promise<Api> {
+    return this.post(seg("users", userId, "mfa", "reset"));
+  }
+
+  /** Give the user permissions directly, beyond their roles' (`posts:write`, `billing:*`). */
+  grant(userId: string, permissions: string[]): Promise<Api> {
+    return this.post(seg("users", userId, "permissions"), { permissions });
+  }
+
+  revoke(userId: string, permissions: string[]): Promise<Api> {
+    return this.del(seg("users", userId, "permissions"), undefined, { permissions });
+  }
+
+  /** Sign the user out everywhere. */
+  revokeSessions(userId: string): Promise<Api> {
+    return this.post(seg("users", userId, "sessions", "revoke"));
+  }
+
+  revokeSession(userId: string, sessionId: string): Promise<Api> {
+    return this.del(seg("users", userId, "sessions", sessionId));
+  }
+
+  devices(userId: string): Promise<Api> {
+    return this.get(seg("users", userId, "devices"));
+  }
+
+  forgetDevice(userId: string, deviceId: string): Promise<Api> {
+    return this.del(seg("users", userId, "devices", deviceId));
+  }
+
+  /** The user's own API keys (never the secrets). */
+  apiKeys(userId: string): Promise<Api> {
+    return this.get(seg("users", userId, "api-keys"));
+  }
+}
+
+export class Roles extends AdminService {
+  /** Roles with their permissions. */
+  list(): Promise<Api> {
+    return this.get("/roles");
+  }
+
+  /** Create or replace a role. Names are lowercase (`editor`, `org:billing`); permissions are `resource:action` patterns with `*` wildcards. */
+  define(name: string, permissions: string[], options: { description?: string } = {}): Promise<Api> {
+    return this.put("/roles", { name, description: options.description ?? "", permissions });
+  }
+
+  remove(name: string): Promise<Api> {
+    return this.del(seg("roles", name));
+  }
+}
+
+/** Organizations (tenants) and their members. A member's role is `owner`, `admin` or `member`. */
+export class Orgs extends AdminService {
+  list(): Promise<Api> {
+    return this.get("/orgs");
+  }
+
+  getOrg(slug: string): Promise<Api> {
+    return this.get(seg("orgs", slug));
+  }
+
+  create(slug: string, name: string, options: { ownerEmail?: string; metadata?: Body } = {}): Promise<Api> {
+    return this.post("/orgs", { slug, name, owner_email: options.ownerEmail, metadata: options.metadata ?? {} });
+  }
+
+  update(slug: string, changes: { name?: string; metadata?: Body }): Promise<Api> {
+    return this.patch(seg("orgs", slug), changes);
+  }
+
+  remove(slug: string): Promise<Api> {
+    return this.del(seg("orgs", slug));
+  }
+
+  /** Add an existing user straight in. */
+  addMember(slug: string, member: { email: string; role?: string }): Promise<Api> {
+    return this.post(seg("orgs", slug, "members"), { email: member.email, role: member.role ?? "member" });
+  }
+
+  setMemberRole(slug: string, userId: string, role: string): Promise<Api> {
+    return this.patch(seg("orgs", slug, "members", userId), { role });
+  }
+
+  removeMember(slug: string, userId: string): Promise<Api> {
+    return this.del(seg("orgs", slug, "members", userId));
+  }
+
+  /** Mail an invitation; `redirectTo` must be one of the environment's allowed redirect URLs. */
+  invite(slug: string, invitation: { email: string; role?: string; redirectTo?: string }): Promise<Api> {
+    return this.post(seg("orgs", slug, "invitations"), { email: invitation.email, role: invitation.role ?? "member", redirect_to: invitation.redirectTo });
+  }
+}
+
+export class Invitations extends AdminService {
+  /** Pending and past invitations across organizations. */
+  list(): Promise<Api> {
+    return this.get("/invitations");
+  }
+
+  resend(invitationId: string, options: { redirectTo?: string } = {}): Promise<Api> {
+    return this.post(seg("invitations", invitationId, "resend"), options.redirectTo ? { redirect_to: options.redirectTo } : {});
+  }
+
+  revoke(invitationId: string): Promise<Api> {
+    return this.del(seg("invitations", invitationId));
+  }
+}
+
+export class Sessions extends AdminService {
+  /** Active sessions across users. */
+  list(options: { limit?: number } = {}): Promise<Api> {
+    return this.get("/sessions", options);
+  }
+
+  /** End one session (all its refresh tokens). */
+  revoke(family: string): Promise<Api> {
+    return this.del(seg("sessions", family));
+  }
+}
+
+/** API keys users made for themselves. */
+export class ApiKeys extends AdminService {
+  list(options: { limit?: number } = {}): Promise<Api> {
+    return this.get("/api-keys", options);
+  }
+
+  revoke(keyId: string): Promise<Api> {
+    return this.del(seg("api-keys", keyId));
+  }
+}
+
+export class Devices extends AdminService {
+  /** Recent devices people signed in from. */
+  list(options: { limit?: number } = {}): Promise<Api> {
+    return this.get("/devices", options);
+  }
+}
+
+/** Events, statistics, identity backup and the hosted pages. */
+export class Insight extends AdminService {
+  /** Authentication events (sign-ins, sign-ups, resets, MFA…). `failed` for failures only. */
+  events(options: { kind?: string; failed?: boolean; limit?: number } = {}): Promise<Api> {
+    return this.get("/events", { kind: options.kind, failed: options.failed ? "true" : undefined, limit: options.limit ?? 100 });
+  }
+
+  /** Counts of users, sign-ins, MFA use and failures. */
+  stats(): Promise<Api> {
+    return this.get("/stats");
+  }
+
+  /** Every identity (users, organizations, roles, factors) as a document. */
+  backup(): Promise<Api> {
+    return this.get("/backup");
+  }
+
+  /** Apply the `identities` of a backup. `dryRun` reports what would change. */
+  restore(identities: Body, options: { replace?: boolean; dryRun?: boolean } = {}): Promise<Api> {
+    return this.post("/restore", { identities, replace: options.replace ?? false, dry_run: options.dryRun ?? false });
+  }
+
+  /** The HTML a hosted sign-in page is served as for the branding being edited (the saved branding when omitted). */
+  /** The claims a token profile would put in a token for this user (and organization), without issuing one. */
+  previewTokenProfile(profile: Body, userId: string, options: { org?: string } = {}): Promise<Api> {
+    return this.post("/token-profiles/preview", { profile, user_id: userId, ...(options.org ? { org: options.org } : {}) });
+  }
+
+  hostedSource(page: string, options: { branding?: Body; form?: Body } = {}): Promise<Api> {
+    return this.post("/hosted-source", { page, branding: options.branding, form: options.form });
+  }
+}
+
+export class Admin {
+  readonly users: Users;
+  readonly roles: Roles;
+  readonly orgs: Orgs;
+  readonly invitations: Invitations;
+  readonly sessions: Sessions;
+  readonly apiKeys: ApiKeys;
+  readonly devices: Devices;
+  readonly insight: Insight;
+
+  constructor(
+    private readonly http: HttpClient,
+    readonly environment: string,
+  ) {
+    this.users = new Users(http, environment);
+    this.roles = new Roles(http, environment);
+    this.orgs = new Orgs(http, environment);
+    this.invitations = new Invitations(http, environment);
+    this.sessions = new Sessions(http, environment);
+    this.apiKeys = new ApiKeys(http, environment);
+    this.devices = new Devices(http, environment);
+    this.insight = new Insight(http, environment);
+  }
+
+  /** The same services for another environment the key may manage. */
+  withEnvironment(name: string): Admin {
+    return new Admin(this.http, name);
+  }
+}
+
+/** User administration for the client's environment (or `environment`). Needs a secret key. */
+export function admin(client: PawabaseClient<any>, environment?: string): Admin {
+  if (!isSecretKey(client.options.apiKey)) {
+    throw new ConfigError("User administration needs a secret key (pb_sk_…).");
+  }
+  return new Admin(client.http, environment ?? client.options.environment ?? "development");
+}