@somewhere-cloud/sdk 0.0.0-stage → 0.13.0

package/dist/types/auth/index.d.ts

@@ -0,0 +1,2 @@
+export * from './client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/auth/index.ts"],"names":[],"mappings":"AAGA,cAAc,aAAa,CAAC"}

package/dist/types/auth/react.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @somewhere-cloud/sdk/react — the "you never touch a token" layer.
+ *
+ *   <SomewhereAuthProvider>
+ *     <SignedIn><Dashboard/></SignedIn>
+ *     <SignedOut><SignIn/></SignedOut>
+ *   </SomewhereAuthProvider>
+ *
+ *   const user = useUser();           // null | User
+ *   const auth = useAuth();           // actions + auth.fetch
+ *
+ * The provider hydrates the user once on mount (validating + refreshing the
+ * session) and re-renders on every login / logout / token rotation.
+ */
+import React from 'react';
+import { type SomewhereAuth, type SomewhereAuthOptions, type User, type Session, type AuthState } from './client.js';
+export declare function SomewhereAuthProvider(props: {
+    options?: SomewhereAuthOptions;
+    /** Pass a pre-created client instead of options, e.g. to share it with
+     *  non-React code. */
+    client?: SomewhereAuth;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * The session as the backend last reported it: status ('checking' |
+ * 'authenticated' | 'signed-out' | 'indeterminate'), the user (last-known and
+ * unverified unless 'authenticated'), and the check error. `recheck()` asks
+ * /me again. Unlike useUser(), this never presents a cached user as verified.
+ */
+export declare function useAuthState(): AuthState & {
+    recheck(): Promise<User | null>;
+};
+/** The current user, or null. Re-renders on login/logout/rotation. */
+export declare function useUser(): User | null;
+/** The raw session tokens (rarely needed — prefer auth.fetch). */
+export declare function useSession(): Session | null;
+/** True until the first session check resolves. */
+export declare function useAuthLoading(): boolean;
+/** The client: actions (signIn, signUp, signOut, …) + auth.fetch. */
+export declare function useAuth(): SomewhereAuth;
+export declare function SignedIn({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element | null;
+/**
+ * Renders `children` when signed out. While a signOut() is waiting for the
+ * server (`useAuthState().signingOut`), the server may still accept the
+ * session, so it renders `pending` instead (default nothing), e.g.
+ * `<SignedOut pending={<p>Signing out…</p>}><SignIn/></SignedOut>`.
+ */
+export declare function SignedOut({ children, pending }: {
+    children: React.ReactNode;
+    pending?: React.ReactNode;
+}): React.JSX.Element | null;
+/** Gate a subtree behind auth; shows `fallback` (default null) when signed
+ *  out, and `pending` (default null) while a signOut() awaits the server. */
+export declare function Protect({ children, fallback, pending }: {
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+    pending?: React.ReactNode;
+}): React.JSX.Element | null;
+/** An explicit server billing observation, separate from sign-in identity. */
+export type BillingObservation = {
+    status: 'ready';
+    features: readonly string[];
+} | {
+    status: 'loading';
+} | {
+    status: 'unavailable';
+};
+/** Local presentation check against an explicit observation; server authorization remains required. */
+export declare function useEntitlements(observation?: BillingObservation): {
+    status: 'ready';
+    has: (feature: string) => boolean;
+    entitlements: readonly string[];
+} | {
+    status: 'loading';
+} | {
+    status: 'unavailable';
+};
+/**
+ * Present a billing feature using an explicit observation from your server.
+ * Loading and unavailable observations have separate presentation from a ready denial.
+ * Server endpoints must still authorize the operation.
+ *
+ *   <Gate billing={billing} feature="export" pending={<Spinner/>}
+ *     unavailable={<Retry/>} fallback={<Upsell/>}><ExportButton/></Gate>
+ */
+export declare function Gate({ billing, feature, children, fallback, pending, unavailable, }: {
+    billing?: BillingObservation;
+    feature: string;
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+    pending?: React.ReactNode;
+    unavailable?: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * Pricing page (sw.billing). Renders the project's code-defined plans,
+ * highlights the user's current plan, and a Subscribe button runs checkout for
+ * the signed-in user (the worker resolves the plan's price from the catalog).
+ *
+ *   <PricingTable/>   // that's it
+ *
+ * Logic-only / unstyled — theme it with the `sw-*` class hooks (sw-pricing-table,
+ * sw-plan[data-current], sw-plan-name/-price/-features/-feature/-cta). Pass
+ * `onSubscribe` to override the default redirect-to-Stripe behavior, `onError`
+ * to surface failures.
+ */
+export declare function PricingTable(props: {
+    className?: string;
+    /** Current plan from an explicit server billing observation. */
+    currentPlan?: string | null;
+    onSubscribe?: (planSlug: string) => void;
+    onError?: (message: string) => void;
+}): React.JSX.Element;
+/**
+ * One-click "manage subscription" (sw.billing) — opens the Stripe billing portal
+ * for the signed-in user (update card, cancel, see invoices). Renders a button;
+ * pass children to set the label (default "Manage billing"). The user can only
+ * ever reach their OWN portal (resolved server-side from their session).
+ *
+ *   <BillingPortal/>            // default label
+ *   <BillingPortal>Manage plan</BillingPortal>
+ */
+export declare function BillingPortal(props: {
+    children?: React.ReactNode;
+    className?: string;
+    onError?: (message: string) => void;
+}): React.JSX.Element;
+/**
+ * Drop this component at an OAuth callback route (the redirect_uri). It
+ * reads `?code=` and completes sign-in, then calls onDone (or navigates to '/').
+ * The app writes no code-exchange logic.
+ */
+export declare function AuthCallback(props: {
+    provider?: 'google' | 'github' | 'discord';
+    onDone?: (user: User) => void;
+    onError?: (message: string) => void;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+//# sourceMappingURL=react.d.ts.map

package/dist/types/auth/react.d.ts.map

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

package/dist/types/auth/server.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @somewhere-cloud/sdk/server — the backend half, so the app writes ~zero auth code.
+ *
+ * Mount it from a single deployed function that handles your /api/auth/* routes:
+ *
+ *   // api/auth/[...path].ts
+ *   import { somewhereAuth } from '@somewhere-cloud/sdk/server';
+ *   export default (req, sw) => somewhereAuth(req, sw);
+ *
+ * It wires the standard endpoints the @somewhere-cloud/sdk/auth client talks to onto
+ * `sw.auth.*` — which already owns the Google OAuth client, JWT validation, and
+ * the bearer-token rotation contract. login/signup are developer-key-gated on the
+ * platform (can't be called from the browser), which is exactly why this thin
+ * server shim exists.
+ *
+ * SESSION TRANSPORT: a successful sign-in sets the session as httpOnly
+ * `__Host-` cookies and answers `{ user, cookie_session: true }` — tokens
+ * never reach page JS. That is the answer for every caller that does not opt
+ * out, including a plain `fetch('/api/auth/login', { credentials: 'include' })`
+ * with no header (pfb_e1254f754222). Only an explicit
+ * `X-Sw-Auth-Mode: header` (aliases `token`, `bearer`) — a server or native
+ * client that holds its own session — receives the token pair in the body, and
+ * then no cookie is set. A runtime that cannot set the cookie refuses
+ * (COOKIE_SESSION_UNAVAILABLE) instead of falling back to tokens.
+ *
+ * Covered today: email/password (signup, login, logout), magic-link/OTP,
+ * email verification for the signed-in account, Google/GitHub/Discord OAuth
+ * (url + exchange), and `me` (validate + refresh).
+ */
+/** The slice of the platform `sw` namespace this handler uses. */
+export interface SwAuthNamespace {
+    auth: {
+        signup(opts: {
+            email: string;
+            password: string;
+            display_name?: string;
+        }): Promise<unknown>;
+        login(opts: {
+            email: string;
+            password: string;
+        }): Promise<unknown>;
+        loginWithCookie?(req: Request, email: string, password: string): Promise<unknown>;
+        signupWithCookie?(req: Request, email: string, password: string, opts?: {
+            display_name?: string;
+        }): Promise<unknown>;
+        mfa?: {
+            challenge?(opts: {
+                mfa_token: string;
+                code: string;
+            }): Promise<unknown>;
+            challengeWithCookie?(opts: {
+                mfa_token: string;
+                code: string;
+            }): Promise<unknown>;
+        };
+        logout(opts: Record<string, unknown>): Promise<unknown>;
+        fromRequest(req: Request, enrich?: unknown): Promise<unknown>;
+        refreshSession?(req: Request): Promise<unknown>;
+        /** Exchanges take the callback's ?code= and its public ?attempt=, which
+         *  selects this browser's attempt cookie; the runtime presents only that
+         *  original request cookie and the platform proves it before spending. */
+        /** Start browser-bound social sign-in: stages this attempt's HttpOnly
+         *  verifier cookie on the response and resolves the provider start URL.
+         *  Optional so the handler answers 501 on a runtime that predates it. The
+         *  old googleUrl/githubUrl/discordUrl builders are not part of this slice:
+         *  current runtimes refuse them, so a current runtime context must satisfy
+         *  this type without them. */
+        oauthStart?(provider: 'google' | 'github' | 'discord', opts: {
+            redirect_uri: string;
+        }): Promise<string>;
+        googleExchange(opts: {
+            code: string;
+            attempt?: string;
+        }): Promise<unknown>;
+        githubExchange(opts: {
+            code: string;
+            attempt?: string;
+        }): Promise<unknown>;
+        discordExchange(opts: {
+            code: string;
+            attempt?: string;
+        }): Promise<unknown>;
+        signInWithOtp(opts: {
+            email: string;
+            redirect_uri?: string;
+        }): Promise<unknown>;
+        verifyOtp(opts: {
+            token: string;
+        }): Promise<unknown>;
+        /** Cookie-session primitives (tsk_1dd4e1b4) — optional so the handler
+         *  degrades to token bodies on runtimes that predate them. */
+        setSessionCookies?(access: string, refresh: string): void;
+        logoutWithCookie?(req: Request): Promise<unknown>;
+        /** Email verification for the request's own session — optional so the
+         *  handler answers 501 on a runtime that predates them. */
+        requestEmailVerificationWithCookie?(req: Request): Promise<unknown>;
+        verifyEmailWithCookie?(req: Request, opts: {
+            code: string;
+        }): Promise<unknown>;
+    };
+    /** Entitlements (sw.billing) — optional so the handler degrades cleanly on a
+     *  runtime that predates it (the /plans route 404s instead of throwing). */
+    billing?: {
+        plans(): Promise<unknown>;
+    };
+    /** Payments (sw.payments) — drives the <PricingTable>/<BillingPortal> flows.
+     *  Optional so the handler degrades cleanly on an older runtime. */
+    payments?: {
+        checkoutForUser(opts: {
+            plan: string;
+            success_url?: string;
+            cancel_url?: string;
+        }): Promise<{
+            url?: string | null;
+        }>;
+        portalForUser(opts: {
+            return_url?: string;
+        }): Promise<{
+            url?: string | null;
+        }>;
+    };
+}
+export declare function somewhereAuth(req: Request, sw: SwAuthNamespace): Promise<Response>;
+//# sourceMappingURL=server.d.ts.map

package/dist/types/auth/server.d.ts.map

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

package/dist/types/client.d.ts

@@ -0,0 +1,128 @@
+import { QueryCache } from './query-cache.js';
+import type { Result, SomewhereOptions } from './types.js';
+/**
+ * Which auth header a request should use.
+ *
+ * - `developer` — always the initial `smt_` key given at construction.
+ *   Developer-only endpoints (`/ai/*`, `/email/*`, `/auth/signup`,
+ *   `/auth/login`, `/auth/logout`, `/auth/forgot`, `/auth/reset`) use
+ *   this mode even if a user session is active — the server rejects
+ *   JWTs on those routes.
+ *
+ * - `dual` — use the user's session JWT if one is active (after
+ *   `auth.signInWithPassword`), otherwise fall back to the initial
+ *   key. This matches the server's dual-auth routes: `/db/query`,
+ *   `/storage/*`, `/fs/*`, `/auth/me`, `/logs`.
+ *
+ * - `session` — require an active user session. Used for routes the
+ *   server only accepts with an app-user JWT (`/auth/users/me`).
+ */
+export type AuthMode = 'developer' | 'dual' | 'session';
+/**
+ * Internal HTTP client. Not exported from the SDK surface — the
+ * `Somewhere` facade owns a single Client instance and passes it to
+ * every resource. Handles auth mode resolution, envelope unwrapping,
+ * typed error materialization, binary round-trips, and the `safeCall`
+ * helper that converts `call` into a `Result<T>` envelope for the
+ * result-envelope surfaces.
+ */
+export declare class Client {
+    readonly baseUrl: string;
+    /** The project's own URL (functions host), if known. See SomewhereOptions.functionsUrl. */
+    readonly functionsUrl?: string;
+    /**
+     * Session transport for `auth.*` (tsk_0de555b1). 'cookie' = httpOnly cookie
+     * sessions via the app's own backend routes — the browser default, because
+     * localStorage tokens are XSS-exfiltratable and httpOnly cookies aren't.
+     * 'header' = Bearer tokens in SDK memory — the default outside browsers
+     * (Node/CLI/native have no httpOnly cookie jar) and the manual/advanced mode.
+     */
+    readonly authMode: 'cookie' | 'header';
+    /** Path the app's backend auth routes are mounted at (cookie mode). */
+    readonly authPath: string;
+    defaultProjectId?: string;
+    private readonly initialAuthHeader;
+    /** Credential supplied at construction, or none for the browser cookie path. */
+    private readonly initialAuthKind;
+    /**
+     * Set by `auth.signInWithPassword` / `auth.signUp` on success.
+     * Cleared by `auth.signOut`. Used by `dual` and `session` auth modes;
+     * NEVER overrides `developer` mode (developer-only endpoints always
+     * use the initial `smt_` key — the server rejects JWTs on them).
+     */
+    private sessionAuthHeader;
+    private readonly fetchImpl;
+    private readonly extraHeaders;
+    /** Surfaces already warned about. Direct browser database and file API calls are disabled;
+     * each surface warns once. */
+    private readonly browserDataWarnings;
+    /**
+     * Instance-scoped query cache for `from().select()`, or `null` when the
+     * caller passed `{ cache: false }`. Consulted by the PostgrestFilterBuilder
+     * executor. Explicit session transitions clear cached and pending reads.
+     */
+    readonly cache: QueryCache | null;
+    constructor(opts: SomewhereOptions);
+    /**
+     * Drop cached `from().select()` reads for a table. Invoked automatically
+     * after a write to the table (read-your-own-writes); also the public seam
+     * for event-driven invalidation. No-op when the cache is disabled.
+     */
+    invalidateTable(table: string): void;
+    /** True when the client was constructed with a developer `smt_` key. */
+    get hasDeveloperKey(): boolean;
+    /** True when a user session is currently active. */
+    get hasSession(): boolean;
+    resolveProjectId(explicit?: string): string | undefined;
+    requireProjectId(explicit?: string, what?: string): string;
+    setSessionToken(accessToken: string): void;
+    clearSession(): void;
+    /**
+     * The `Authorization` value a project-function call should carry: the
+     * active user session if signed in, else the construction key/token.
+     * Same precedence as `dual` mode.
+     */
+    get sessionOrInitialBearer(): string;
+    /** Low-level fetch passthrough for absolute URLs (project function hosts). */
+    rawFetch(url: string, init: RequestInit): Promise<Response>;
+    private authHeader;
+    /** JSON request → JSON response. Unwraps `{ok, data}` → `data`, throws on error. */
+    call<T = unknown>(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', path: string, opts?: {
+        body?: unknown;
+        query?: Record<string, unknown>;
+        auth?: AuthMode;
+        signal?: AbortSignal;
+        /** Session credential for this request only; never installs client state. */
+        sessionBearer?: string;
+    }): Promise<T>;
+    /**
+     * Same as `call` but never throws — always returns a `Result<T>`.
+     * Used by result-envelope surfaces where the caller branches
+     * on `.error` instead of catching.
+     */
+    safeCall<T>(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', path: string, opts?: {
+        body?: unknown;
+        query?: Record<string, unknown>;
+        auth?: AuthMode;
+    }): Promise<Result<T>>;
+    /** Raw binary download. */
+    getBytes(path: string, query?: Record<string, unknown>, auth?: AuthMode): Promise<{
+        body: ArrayBuffer;
+        contentType: string;
+    }>;
+    /** Raw binary upload. */
+    putBytes<T = unknown>(path: string, body: BodyInit, contentType: string, auth?: AuthMode): Promise<T>;
+    /**
+     * Direct browser calls to the platform's database and file APIs are
+     * disabled; browser code uses declared data/file collections or a server
+     * function. This one-time warning says so. It does not block or alter the
+     * request: the server decides, and the caller gets that answer as a normal
+     * Result. Server-side use of these APIs is unaffected.
+     */
+    private warnOnDirectBrowserDataAccess;
+    private buildUrl;
+    private parseJson;
+    private unwrap;
+    private toError;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/types/client.d.ts.map

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

package/dist/types/errors.d.ts

@@ -0,0 +1,17 @@
+export interface SomewhereErrorInit {
+    code: string;
+    message: string;
+    statusCode: number;
+    retry: boolean;
+    retryAfterMs: number | null;
+    body?: unknown;
+}
+export declare class SomewhereError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly retry: boolean;
+    readonly retryAfterMs: number | null;
+    readonly body: unknown;
+    constructor(init: SomewhereErrorInit);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,IAAI,EAAE,kBAAkB;CASrC"}

package/dist/types/index.d.ts

@@ -0,0 +1,145 @@
+import { AuthClient } from './resources/auth.js';
+import { CallsClient } from './resources/calls.js';
+import { ChatClient } from './resources/chat.js';
+import { DbClient } from './resources/db.js';
+import { EmailsClient } from './resources/emails.js';
+import { FsClient } from './resources/fs.js';
+import { FunctionsClient } from './resources/functions.js';
+import { InboxClient } from './resources/inbox.js';
+import { PaymentsClient } from './resources/payments.js';
+import { SomewhereQueryBuilder } from './resources/postgrest.js';
+import type { Result } from './types.js';
+import { StorageClient } from './resources/storage.js';
+import { TasksClient } from './resources/tasks.js';
+import { ProjectsClient } from './resources/projects.js';
+import { VideoClient } from './resources/video.js';
+import type { CreateClientOptions, SomewhereOptions } from './types.js';
+export { SomewhereError } from './errors.js';
+export type { SomewhereErrorInit } from './errors.js';
+export type * from './types.js';
+export type { UploadOptions } from './resources/storage.js';
+export { PostgrestFilterBuilder, SomewhereQueryBuilder } from './resources/postgrest.js';
+export type { CountMode } from './resources/postgrest.js';
+export { QueryCache } from './query-cache.js';
+export type { CacheOptions } from './query-cache.js';
+export { StorageClient, StorageFileApi } from './resources/storage.js';
+export { AuthClient } from './resources/auth.js';
+export { DbClient } from './resources/db.js';
+export { EmailsClient } from './resources/emails.js';
+export { FsClient } from './resources/fs.js';
+export { FunctionsClient } from './resources/functions.js';
+export { ChatClient, ChatCompletionsClient } from './resources/chat.js';
+export { PaymentsClient } from './resources/payments.js';
+export { VideoClient } from './resources/video.js';
+export { InboxClient, InboxAddressesClient, InboxMessagesClient } from './resources/inbox.js';
+export { CallsClient } from './resources/calls.js';
+export { TasksClient } from './resources/tasks.js';
+export type { Task, CreateTaskInput, UpdateTaskInput, TaskListOptions } from './resources/tasks.js';
+export { ProjectsClient } from './resources/projects.js';
+export type { ProjectSeoMetadata, SeoMetadataItem, SeoStatus } from './resources/projects.js';
+export type { AnalyticsConsentPolicy, ProjectUpdateInput, ProjectUpdateResult, ProjectAllowedOrigins } from './resources/projects.js';
+export type { SomewhereOptions };
+/**
+ * The somewhere.tech client for explicit server and non-browser access, plus
+ * browser auth and application-function conveniences:
+ *
+ *   - `sw.db.query(sql, params)`     — raw SQL
+ *   - `sw.db.from(table)` / `sw.from(table)` — fluent query builder
+ *   - `sw.fs.read(path)` / `sw.fs.write(path, body)` — raw filesystem
+ *   - `sw.storage.from(bucket)`      — prefix-oriented file API
+ *   - `sw.auth`                      — application auth
+ *   - `sw.emails.send(...)`          — Resend email
+ *   - `sw.inbox.messages.list(...)`  — inbound email
+ *   - `sw.chat.completions.create()` — OpenAI chat completions
+ *   - `sw.payments.checkout(...)`    — Stripe Connect (zero platform fee)
+ *   - `sw.video.createUploadUrl()`   — direct-upload video pipeline
+ *   - `sw.calls.createSession()`     — WebRTC SFU sessions
+ *   - `sw.tasks.create(...)`         — per-project ticketing
+ *
+ *     import { Somewhere } from '@somewhere-cloud/sdk'
+ *     const sw = new Somewhere({ key: process.env.SOMEWHERE_API_KEY, projectId: 'booking-app' })
+ *
+ *     const { data } = await sw.from('users').select('*').eq('id', 1)
+ */
+export declare class Somewhere {
+    readonly auth: AuthClient;
+    readonly db: DbClient;
+    readonly fs: FsClient;
+    readonly storage: StorageClient;
+    readonly emails: EmailsClient;
+    readonly inbox: InboxClient;
+    readonly chat: ChatClient;
+    readonly payments: PaymentsClient;
+    readonly functions: FunctionsClient;
+    readonly video: VideoClient;
+    readonly calls: CallsClient;
+    readonly tasks: TasksClient;
+    readonly projects: ProjectsClient;
+    private readonly client;
+    constructor(opts: SomewhereOptions);
+    /** Fluent query builder entry point. Alias of `sw.db.from(table)`. */
+    from(table: string): SomewhereQueryBuilder;
+    /**
+     * Warm the client cache for a query ahead of need — hover-prefetch, route
+     * preload, "load the next page while they read this one". Just runs the
+     * query (populating the instance cache); a later identical `.select()`
+     * within the staleTime window is then served instantly from cache.
+     *
+     *     sw.prefetch(sw.from('posts').select('*').eq('id', hoveredId))
+     *     // …on click, this is a cache hit, no network round-trip:
+     *     const { data } = await sw.from('posts').select('*').eq('id', hoveredId)
+     *
+     * No-op for cache effects when the client was created with `{ cache: false }`.
+     */
+    prefetch<T = unknown>(query: PromiseLike<Result<T>>): Promise<Result<T>>;
+    /**
+     * Drop cached `from().select()` reads for a table. Read-your-own-writes is
+     * already automatic (writes self-invalidate); reach for this to invalidate
+     * by hand — e.g. from whatever tells your app a row changed:
+     *
+     *     onRowChanged('posts', () => sw.invalidate('posts'))
+     */
+    invalidate(table: string): void;
+    /**
+     * `rpc(name, args)` convenience method. On somewhere there are no SQL stored
+     * procedures — a "database function" is one of your deployed `api/<name>`
+     * functions. `rpc('foo', args)` therefore calls `POST {projectUrl}/api/foo`
+     * with `args` as the JSON body and returns `{ data, error }`. Identical to
+     * `functions.invoke(name, { body: args })`; provided so existing `rpc(...)`
+     * call sites port unchanged.
+     */
+    rpc<T = unknown>(name: string, args?: Record<string, unknown>): Promise<Result<T>>;
+}
+export default Somewhere;
+/**
+ * Derive the project id from a legacy `*.somewhere.tech` application URL's
+ * subdomain. Current `*.somewhere.site` URLs, custom domains, API hosts, and
+ * bare hosts return `undefined`; pass `projectId` explicitly for project
+ * resources. The seam is loud: an unresolved project id surfaces as a clear
+ * error on the first call that needs one.
+ */
+export declare function projectIdFromUrl(url: string): string | undefined;
+/**
+ * Create a somewhere.tech client from an application URL:
+ *
+ *     import { createClient } from '@somewhere-cloud/sdk'
+ *     const client = createClient('https://booking-app.somewhere.site', undefined, {
+ *       projectId: 'booking-app',
+ *     })
+ *
+ *     await client.auth.signInWithPassword({ email, password })
+ *     await client.functions.invoke('checkout', { body: { plan: 'pro' } })
+ *
+ * - `somewhereUrl` — your application's URL. Used as the `functions.invoke`
+ *   host. Pass `{ projectId }` for current `*.somewhere.site` URLs and custom
+ *   domains; automatic inference is retained for legacy `*.somewhere.tech`
+ *   application URLs only.
+ * - `somewhereKey` — omit in a browser cookie app. For non-browser use, pass
+ *   an app-user JWT or a developer `smt_` key
+ *   (server-only). Detected by the `smt_` prefix.
+ *
+ * Database / auth / storage calls go to the platform REST base
+ * (`https://api.somewhere.cloud/v1`, override with `options.apiUrl`).
+ */
+export declare function createClient(somewhereUrl: string, somewhereKey?: string, options?: CreateClientOptions): Somewhere;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

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

package/dist/types/query-cache.d.ts

@@ -0,0 +1,59 @@
+import type { Result } from './types.js';
+/**
+ * Client-side query cache for the `from().select()` read path.
+ *
+ * Three jobs, all default-on (the founder's call — see
+ * `docs/platform-intelligence.md`):
+ *
+ *  1. **Request dedup / single-flight.** Two awaits of the same query while
+ *     the first is still in flight share ONE network request within a generation.
+ *  2. **Short staleTime cache (~1s).** A repeat read within `staleTime` of the
+ *     last fetch returns the prior result instead of refetching. 1s is the
+ *     safety knob: own-writes invalidate (below), normal polling (>1s apart)
+ *     stays fresh, only sub-second bursts coalesce.
+ *  3. **Invalidate-on-write.** A write to a table drops that table's cached
+ *     reads so the next read is fresh (read-your-own-writes correctness).
+ *
+ * The cache is owned by a single `Client` instance. Session transitions
+ * clear its entries and detach pending reads from the next session.
+ *
+ * EVENT-INVALIDATION SEAM (future, not built here): a change event for a
+ * table should call {@link QueryCache.invalidate} for that table — the exact
+ * same path invalidate-on-write uses. That's the whole integration point.
+ */
+export interface CacheOptions {
+    /** Milliseconds a fetched read stays fresh before a refetch. Default 1000. */
+    staleTime?: number;
+}
+export declare class QueryCache {
+    private readonly staleTime;
+    private readonly entries;
+    private readonly inFlight;
+    /**
+     * Per-table generation counter. Bumped on every invalidate so a fetch that
+     * was already in flight when its table got invalidated does NOT repopulate
+     * the cache with a pre-write value.
+     */
+    private readonly generations;
+    private readonly now;
+    constructor(opts?: CacheOptions, now?: () => number);
+    /**
+     * Read-through with dedup + staleTime. `run` performs the actual network
+     * fetch and is invoked at most once per in-flight key and generation.
+     * `fresh` bypasses hits and dedup but still fences cache warming on invalidation.
+     */
+    read(key: string, table: string, run: () => Promise<Result<unknown>>, fresh?: boolean): Promise<Result<unknown>>;
+    /**
+     * Store a current result directly. Reads that can overlap invalidation
+     * should use `read` so their cache warming is generation-checked.
+     */
+    store(key: string, table: string, result: Result<unknown>): void;
+    /**
+     * Drop every cached read for a table. Called automatically after a write to
+     * that table (read-your-own-writes); also the public event/manual seam.
+     */
+    invalidate(table: string): void;
+    /** Drop the entire cache and detach pending reads. */
+    clear(): void;
+}
+//# sourceMappingURL=query-cache.d.ts.map