@sovaria/sdk 0.0.0-stage → 0.4.0

package/dist/errors.js

@@ -0,0 +1,246 @@
+/**
+ * Errors thrown by the SDK.
+ *
+ * `message` is written for the people using your app ("You don't have permission to do that."),
+ * so `catch (e) { show(e.message) }` never leaks policy names, table names or SQL to end users.
+ * The server's own text stays available for developers in `technicalMessage` / `detail`,
+ * and `code` is a stable value to branch on.
+ */
+const FRIENDLY = {
+    NETWORK_ERROR: "Can't reach the server. Check your connection and try again.",
+    UNAUTHENTICATED: 'Your session has ended. Please sign in again.',
+    PERMISSION_DENIED: "You don't have permission to do that.",
+    NOT_FOUND: "We couldn't find what you were looking for.",
+    CONFLICT: 'That already exists or was changed by someone else.',
+    INVALID_INPUT: 'Some of the information entered is not valid.',
+    PAYLOAD_TOO_LARGE: 'That file or request is too large.',
+    UNSUPPORTED_TYPE: "That file type isn't allowed here.",
+    RATE_LIMITED: 'Too many requests. Please wait a moment and try again.',
+    PLAN_LIMIT_REACHED: "This project has reached its plan limit.",
+    PLAN_FEATURE_REQUIRED: "This feature isn't available on the current plan.",
+    PLAN_QUOTA_EXHAUSTED: "This project's usage quota is used up for now.",
+    SERVICE_UNAVAILABLE: 'The service is busy right now. Please try again shortly.',
+    SERVER_ERROR: 'Something went wrong on our side. Please try again.',
+    BAD_REQUEST: "That request couldn't be completed.",
+    CONFIG_ERROR: 'The app is not configured correctly.',
+    UNKNOWN: 'Something went wrong. Please try again.',
+};
+const PLAN_CODES = new Set(['PLAN_LIMIT_REACHED', 'PLAN_FEATURE_REQUIRED', 'PLAN_QUOTA_EXHAUSTED']);
+function serverText(detail) {
+    if (detail == null)
+        return '';
+    if (typeof detail === 'string')
+        return detail;
+    if (Array.isArray(detail))
+        return detail.map(serverText).filter(Boolean).join('; ');
+    if (typeof detail === 'object') {
+        const d = detail;
+        for (const key of ['detail', 'message', 'msg', 'error', 'error_description']) {
+            if (d[key] != null) {
+                const text = serverText(d[key]);
+                if (text)
+                    return text;
+            }
+        }
+        try {
+            return JSON.stringify(detail);
+        }
+        catch {
+            return String(detail);
+        }
+    }
+    return String(detail);
+}
+function explicitCode(detail) {
+    if (!detail || typeof detail !== 'object' || Array.isArray(detail))
+        return undefined;
+    const d = detail;
+    if (typeof d.code === 'string')
+        return d.code;
+    for (const key of ['detail', 'error']) {
+        const inner = explicitCode(d[key]);
+        if (inner)
+            return inner;
+    }
+    return undefined;
+}
+function planMessage(detail) {
+    if (!detail || typeof detail !== 'object' || Array.isArray(detail))
+        return undefined;
+    const d = detail;
+    if (typeof d.code === 'string' && PLAN_CODES.has(d.code) && typeof d.message === 'string')
+        return d.message;
+    for (const key of ['detail', 'error']) {
+        const inner = planMessage(d[key]);
+        if (inner)
+            return inner;
+    }
+    return undefined;
+}
+/** FastAPI/pydantic validation errors: [{loc: [..., "field"], msg}] → "title: field required". */
+function validationMessage(detail) {
+    const items = Array.isArray(detail)
+        ? detail
+        : detail && typeof detail === 'object' && Array.isArray(detail.detail)
+            ? (detail.detail)
+            : undefined;
+    if (!items?.length)
+        return undefined;
+    const first = items[0];
+    if (typeof first?.msg !== 'string')
+        return undefined;
+    const field = Array.isArray(first.loc) ? first.loc.filter((p) => typeof p === 'string' && p !== 'body').pop() : undefined;
+    const raw = first.msg.replace(/^Value error, /, '');
+    const plain = humanizeValidation(raw);
+    const name = field ? capitalize(String(field).replace(/_/g, ' ')) : '';
+    if (plain)
+        return name ? `${name} ${plain}` : capitalize(plain);
+    return name ? `${name}: ${raw}` : capitalize(raw);
+}
+function capitalize(text) {
+    return text ? text.charAt(0).toUpperCase() + text.slice(1) : text;
+}
+/** pydantic wording → plain English, phrased to follow the field name ("Email is required."). */
+function humanizeValidation(msg) {
+    const rules = [
+        [/^Field required$/i, () => 'is required.'],
+        [/^String should have at least (\d+) characters?$/i, (m) => `must be at least ${m[1]} characters.`],
+        [/^String should have at most (\d+) characters?$/i, (m) => `must be at most ${m[1]} characters.`],
+        [/^Input should be greater than or equal to (\S+)$/i, (m) => `must be ${m[1]} or more.`],
+        [/^Input should be less than or equal to (\S+)$/i, (m) => `must be ${m[1]} or less.`],
+        [/^Input should be a valid (\w+)/i, (m) => `must be a valid ${m[1]}.`],
+        [/not a valid email address/i, () => 'is not a valid email address.'],
+        [/^String should match pattern/i, () => 'is not in the right format.'],
+    ];
+    for (const [re, fmt] of rules) {
+        const m = msg.match(re);
+        if (m)
+            return fmt(m);
+    }
+    return undefined;
+}
+/** Postgres constraint text that is safe and useful to show (no table or policy names). */
+function databaseMessage(text) {
+    const t = text.toLowerCase();
+    if (t.includes('row-level security') || t.includes('guard denied') || t.includes('permission denied')) {
+        return { code: 'PERMISSION_DENIED', message: FRIENDLY.PERMISSION_DENIED };
+    }
+    if (t.includes('duplicate key') || t.includes('unique constraint')) {
+        return { code: 'CONFLICT', message: 'That already exists.' };
+    }
+    if (t.includes('violates foreign key')) {
+        return { code: 'CONFLICT', message: 'That refers to something that no longer exists, or is still in use.' };
+    }
+    if (t.includes('violates check constraint') || t.includes('violates not-null') || t.includes('invalid input syntax')) {
+        return { code: 'INVALID_INPUT', message: FRIENDLY.INVALID_INPUT };
+    }
+    if (t.includes('value too long'))
+        return { code: 'INVALID_INPUT', message: 'One of the values is too long.' };
+    return undefined;
+}
+function classify(status, detail) {
+    const raw = explicitCode(detail);
+    if (raw && PLAN_CODES.has(raw)) {
+        return { code: raw, message: planMessage(detail) ?? FRIENDLY[raw] };
+    }
+    const text = serverText(detail);
+    const db = databaseMessage(text);
+    if (status === 0)
+        return { code: 'NETWORK_ERROR', message: FRIENDLY.NETWORK_ERROR };
+    if (status === 401)
+        return { code: 'UNAUTHENTICATED', message: FRIENDLY.UNAUTHENTICATED };
+    if (status === 403)
+        return { code: 'PERMISSION_DENIED', message: FRIENDLY.PERMISSION_DENIED };
+    if (db)
+        return db;
+    if (status === 404)
+        return { code: 'NOT_FOUND', message: FRIENDLY.NOT_FOUND };
+    if (status === 409)
+        return { code: 'CONFLICT', message: FRIENDLY.CONFLICT };
+    if (status === 413)
+        return { code: 'PAYLOAD_TOO_LARGE', message: FRIENDLY.PAYLOAD_TOO_LARGE };
+    if (status === 415)
+        return { code: 'UNSUPPORTED_TYPE', message: FRIENDLY.UNSUPPORTED_TYPE };
+    if (status === 422)
+        return { code: 'INVALID_INPUT', message: validationMessage(detail) ?? FRIENDLY.INVALID_INPUT };
+    if (status === 429)
+        return { code: 'RATE_LIMITED', message: FRIENDLY.RATE_LIMITED };
+    if (status === 502 || status === 503 || status === 504) {
+        return { code: 'SERVICE_UNAVAILABLE', message: FRIENDLY.SERVICE_UNAVAILABLE };
+    }
+    if (status >= 500)
+        return { code: 'SERVER_ERROR', message: FRIENDLY.SERVER_ERROR };
+    if (status === 400)
+        return { code: 'BAD_REQUEST', message: FRIENDLY.BAD_REQUEST };
+    return { code: 'UNKNOWN', message: FRIENDLY.UNKNOWN };
+}
+export class SovariaError extends Error {
+    /** HTTP status (0 when the request never got a response). */
+    statusCode;
+    /** The server's response body (or the SDK's own explanation). */
+    detail;
+    /** Stable category to branch on. */
+    code;
+    /** The server code when one was sent (e.g. PLAN_LIMIT_REACHED), else `code`. */
+    serverCode;
+    /** `HTTP <status>: <server text>` — for logs and developers, not for end users. */
+    technicalMessage;
+    /**
+     * The request's trace id (W3C traceparent). In the console, Logs › Request traces (or
+     * `sov.api.observability…` / `sov logs why <id>`) says which check refused the request and why.
+     */
+    traceId;
+    constructor(statusCode, detail, code) {
+        const classified = code
+            ? { code, message: code === 'CONFIG_ERROR' && typeof detail === 'string' ? detail : FRIENDLY[code] }
+            : classify(statusCode, detail);
+        super(classified.message);
+        this.name = 'SovariaError';
+        this.statusCode = statusCode;
+        this.detail = detail;
+        this.code = classified.code;
+        this.serverCode = explicitCode(detail) ?? classified.code;
+        this.technicalMessage = `HTTP ${statusCode}: ${serverText(detail)}`;
+    }
+    /** Attach the request's trace id (kept in `technicalMessage` for logs). */
+    withTraceId(traceId) {
+        if (traceId) {
+            this.traceId = traceId;
+            this.technicalMessage = `${this.technicalMessage} (trace ${traceId})`;
+        }
+        return this;
+    }
+    /** A mistake in how the SDK is set up or called; the message is written for the developer. */
+    static config(message, statusCode = 400) {
+        return new SovariaError(statusCode, message, 'CONFIG_ERROR');
+    }
+    /** The message to show your users (same as `message`). */
+    get userMessage() {
+        return this.message;
+    }
+    toString() {
+        return `SovariaError [${this.code}] ${this.message} (${this.technicalMessage})`;
+    }
+}
+/** A friendly message for any thrown value: SovariaError text as-is, anything else generic. */
+export function userMessageFor(error, fallback = FRIENDLY.UNKNOWN) {
+    if (error instanceof SovariaError)
+        return error.message;
+    if (error instanceof TypeError && /fetch|network/i.test(error.message))
+        return FRIENDLY.NETWORK_ERROR;
+    return fallback;
+}
+/** A W3C trace id (32 hex) for one logical request; every retry of it shares the id. */
+export function newTraceId() {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto?.getRandomValues?.(bytes);
+    if (bytes.every((b) => b === 0))
+        for (let i = 0; i < 16; i += 1)
+            bytes[i] = Math.floor(Math.random() * 256);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** `traceparent` for one attempt: the request's trace id and a fresh span id. */
+export function traceparentFor(traceId) {
+    const span = newTraceId().slice(0, 16);
+    return `00-${traceId}-${span}-01`;
+}

package/dist/firestore.d.ts

@@ -0,0 +1,176 @@
+import { type DocumentSnapshot as SovDocumentSnapshot, DocumentReference as SovDocumentReference, Query as SovQuery, type QuerySnapshot as SovQuerySnapshot, Transaction as SovTransaction, WriteBatch as SovWriteBatch, type WhereOp } from './collections.js';
+export type DocumentData = Record<string, any>;
+export type WhereFilterOp = WhereOp;
+export type OrderByDirection = 'asc' | 'desc';
+export type Unsubscribe = () => void;
+export interface SetOptions {
+    merge?: boolean;
+    mergeFields?: string[];
+}
+/** What getFirestore needs from a Sovaria client (any `SovariaSDK`). */
+import { type OfflineStorage } from './offline.js';
+export interface SovariaLike {
+    collection<T = any>(path: string): SovQuery<T>;
+    doc<T = any>(path: string): SovDocumentReference<T>;
+    batch(): SovWriteBatch;
+    runTransaction<R>(fn: (tx: SovTransaction) => Promise<R>, maxAttempts?: number): Promise<R>;
+}
+export declare class Firestore {
+    readonly sov: SovariaLike;
+    readonly type = "firestore";
+    constructor(sov: SovariaLike);
+}
+/** The Firestore handle for a Sovaria client. */
+export declare function getFirestore(sov: SovariaLike): Firestore;
+export type LocalCache = {
+    kind: 'persistent' | 'memory';
+    storage?: OfflineStorage;
+};
+/** Firebase's `persistentLocalCache()`: IndexedDB in browsers (memory where there is none). */
+export declare function persistentLocalCache(options?: {
+    storage?: OfflineStorage;
+}): LocalCache;
+/** Firebase's `memoryLocalCache()`: offline cache for this page/process only. */
+export declare function memoryLocalCache(): LocalCache;
+/** `initializeFirestore(sov, { localCache: persistentLocalCache() })` turns on offline mode, like Firebase. */
+export declare function initializeFirestore(sov: SovariaLike, settings?: {
+    localCache?: LocalCache;
+}): Firestore;
+/** Firebase's (older) way to turn on the persistent cache. */
+export declare function enableIndexedDbPersistence(db: Firestore): Promise<void>;
+export declare class DocumentReference<T = DocumentData> {
+    readonly firestore: Firestore;
+    readonly _ref: SovDocumentReference<T>;
+    readonly type = "document";
+    constructor(firestore: Firestore, _ref: SovDocumentReference<T>);
+    get id(): string;
+    get path(): string;
+    get parent(): CollectionReference<T>;
+}
+export declare class Query<T = DocumentData> {
+    readonly firestore: Firestore;
+    readonly _query: SovQuery<T>;
+    readonly type: 'query' | 'collection';
+    constructor(firestore: Firestore, _query: SovQuery<T>);
+}
+export declare class CollectionReference<T = DocumentData> extends Query<T> {
+    readonly type: "collection";
+    get id(): string;
+    get path(): string;
+}
+type Parent = Firestore | CollectionReference<any> | DocumentReference<any>;
+/** `collection(db, 'users')`, `collection(db, 'users', uid, 'posts')`, `collection(docRef, 'posts')`. */
+export declare function collection<T = DocumentData>(parent: Parent, path: string, ...segments: string[]): CollectionReference<T>;
+/** `doc(db, 'users', uid)`, `doc(db, 'users/uid')`, `doc(collectionRef)` (new id), `doc(collectionRef, id)`. */
+export declare function doc<T = DocumentData>(parent: Parent, path?: string, ...segments: string[]): DocumentReference<T>;
+/** `where(documentId(), '==', id)` filters on the document id. */
+export declare function documentId(): string;
+export type QueryConstraint = (q: SovQuery<any>) => SovQuery<any>;
+export declare function where(field: string, op: WhereFilterOp, value: unknown): QueryConstraint;
+export declare function orderBy(field: string, direction?: OrderByDirection): QueryConstraint;
+export declare function limit(n: number): QueryConstraint;
+export declare function limitToLast(n: number): QueryConstraint;
+export declare function startAt(...values: unknown[]): QueryConstraint;
+export declare function startAfter(...values: unknown[]): QueryConstraint;
+export declare function endAt(...values: unknown[]): QueryConstraint;
+export declare function endBefore(...values: unknown[]): QueryConstraint;
+export declare function query<T = DocumentData>(base: Query<T>, ...constraints: QueryConstraint[]): Query<T>;
+export declare class DocumentSnapshot<T = DocumentData> {
+    readonly ref: DocumentReference<T>;
+    readonly _snap: SovDocumentSnapshot<T>;
+    constructor(ref: DocumentReference<T>, _snap: SovDocumentSnapshot<T>);
+    get id(): string;
+    exists(): boolean;
+    data(): T | undefined;
+    /** A field by dotted path (`get('address.city')`). */
+    get(field: string): any;
+    /** Offline mode (enableIndexedDbPersistence / persistentLocalCache): from the cache, or a write not yet synced. */
+    get metadata(): {
+        hasPendingWrites: boolean;
+        fromCache: boolean;
+    };
+}
+export declare class QueryDocumentSnapshot<T = DocumentData> extends DocumentSnapshot<T> {
+    data(): T;
+}
+export interface DocumentChange<T = DocumentData> {
+    type: 'added' | 'modified' | 'removed';
+    doc: QueryDocumentSnapshot<T>;
+    oldIndex: number;
+    newIndex: number;
+}
+export declare class QuerySnapshot<T = DocumentData> {
+    readonly query: Query<T>;
+    readonly docs: QueryDocumentSnapshot<T>[];
+    private readonly changes;
+    constructor(query: Query<T>, raw: SovQuerySnapshot<T>);
+    get size(): number;
+    get empty(): boolean;
+    forEach(callback: (doc: QueryDocumentSnapshot<T>) => void): void;
+    docChanges(): DocumentChange<T>[];
+    /** Offline mode: answered from the cache, or holding writes not yet synced. */
+    get metadata(): {
+        hasPendingWrites: boolean;
+        fromCache: boolean;
+    };
+}
+export declare function getDoc<T = DocumentData>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+export declare function getDocs<T = DocumentData>(q: Query<T>): Promise<QuerySnapshot<T>>;
+export declare function getCountFromServer(q: Query<any>): Promise<{
+    data: () => {
+        count: number;
+    };
+}>;
+type Observer<S> = {
+    next?: (snap: S) => void;
+    error?: (error: unknown) => void;
+};
+/** Live document or query. Returns its unsubscribe function right away, like Firebase. */
+export declare function onSnapshot<T = DocumentData>(target: DocumentReference<T> | Query<T>, onNextOrObserver: ((snap: any) => void) | Observer<any>, onError?: (error: unknown) => void): Unsubscribe;
+/** A point in time. Stored as an ISO-8601 string in Sovaria. */
+export declare class Timestamp {
+    readonly seconds: number;
+    readonly nanoseconds: number;
+    constructor(seconds: number, nanoseconds: number);
+    static now(): Timestamp;
+    static fromDate(date: Date): Timestamp;
+    static fromMillis(ms: number): Timestamp;
+    /** Read back a stored timestamp (an ISO string) as a Timestamp. */
+    static fromIso(value: string): Timestamp;
+    toMillis(): number;
+    toDate(): Date;
+    toISOString(): string;
+    isEqual(other: Timestamp): boolean;
+}
+export declare function serverTimestamp(): import("./collections.js").FieldTransform;
+export declare function increment(n: number): import("./collections.js").FieldTransform;
+export declare function arrayUnion(...elements: unknown[]): import("./collections.js").FieldTransform;
+export declare function arrayRemove(...elements: unknown[]): import("./collections.js").FieldTransform;
+export declare function deleteField(): import("./collections.js").FieldTransform;
+export declare function setDoc<T = DocumentData>(ref: DocumentReference<T>, data: Partial<T> & DocumentData, options?: SetOptions): Promise<void>;
+export declare function addDoc<T = DocumentData>(ref: CollectionReference<T>, data: Partial<T> & DocumentData): Promise<DocumentReference<T>>;
+/** `updateDoc(ref, {a: 1})` or `updateDoc(ref, 'a', 1, 'b.c', 2)`. */
+export declare function updateDoc(ref: DocumentReference<any>, dataOrField: string | DocumentData, ...rest: unknown[]): Promise<void>;
+export declare function deleteDoc(ref: DocumentReference<any>): Promise<void>;
+export declare class WriteBatch {
+    private readonly batch;
+    constructor(batch: SovWriteBatch);
+    set(ref: DocumentReference<any>, data: DocumentData, options?: SetOptions): WriteBatch;
+    update(ref: DocumentReference<any>, dataOrField: string | DocumentData, ...rest: unknown[]): WriteBatch;
+    delete(ref: DocumentReference<any>): WriteBatch;
+    commit(): Promise<void>;
+}
+export declare function writeBatch(db: Firestore): WriteBatch;
+export declare class Transaction {
+    private readonly tx;
+    constructor(tx: SovTransaction);
+    get<T = DocumentData>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+    set(ref: DocumentReference<any>, data: DocumentData, options?: SetOptions): Transaction;
+    update(ref: DocumentReference<any>, dataOrField: string | DocumentData, ...rest: unknown[]): Transaction;
+    delete(ref: DocumentReference<any>): Transaction;
+}
+/** Reads then writes atomically; retried when a document it read changed meanwhile (default 5 attempts). */
+export declare function runTransaction<R>(db: Firestore, fn: (tx: Transaction) => Promise<R>, options?: {
+    maxAttempts?: number;
+}): Promise<R>;
+export {};