@sovaria/sdk 0.0.0-stage → 0.5.0

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+export interface SovariaClientOptions {
+    accessToken?: string;
+    refreshToken?: string;
+    onTokenRefresh?: (tokens: TokenResponse) => void;
+}
+export { SovariaError } from './errors.js';
+export interface TokenResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    token_type?: string;
+}
+export interface UserProfile {
+    user_id?: string;
+    email?: string;
+    org_id?: string;
+    project_id?: string;
+    roles?: string[];
+    [key: string]: unknown;
+}
+export interface NodeResponse {
+    node_id?: string;
+    id?: string;
+    type?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ColumnDefinition {
+    name: string;
+    type: string;
+    nullable?: boolean;
+    primary_key?: boolean;
+    default?: unknown;
+}
+export interface SqlQueryResult {
+    rows: Record<string, unknown>[];
+    row_count?: number;
+}
+export interface DocumentPutResponse {
+    ok?: boolean;
+    key?: string;
+    [key: string]: unknown;
+}
+export interface DocumentGetResponse {
+    key?: string;
+    value?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface DocumentScanResult {
+    items?: Array<Record<string, unknown>>;
+    count?: number;
+    [key: string]: unknown;
+}
+export interface StorageObject {
+    path: string;
+    size?: number;
+    content_type?: string;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface Bucket {
+    name: string;
+    public?: boolean;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface BucketListResponse {
+    buckets: Bucket[];
+}
+export interface ObjectListResponse {
+    objects: StorageObject[];
+}
+export interface FunctionDeployResponse {
+    deployment_id?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface FunctionInvokeResponse {
+    output?: unknown;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface RealtimeEvent {
+    type: string;
+    channel: string;
+    payload: unknown;
+}
+export type RealtimeCallback = (event: RealtimeEvent) => void;
+export interface RealtimeSubscription {
+    unsubscribe: () => void;
+}
+export interface TimelineLogResponse {
+    timeline?: string;
+    events?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+export interface TimelineJumpResponse {
+    timeline?: string;
+    target_hex?: string;
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export { SovariaError } from './errors.js';

package/dist/webpush.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Web push for browsers (Chrome, Edge, Firefox, Safari 16.4+ including iOS home-screen web apps), with the project's
+ * own VAPID keys — no Firebase project needed.
+ *
+ * ```ts
+ * // 1. Serve the service worker at your site's root: copy `serviceWorkerSource` into /sovaria-sw.js
+ * //    (or importScripts it from your own worker).
+ * // 2. After the user signs in, from a click handler (browsers require a user gesture):
+ * await sov.push.register({ topics: ['news'] })
+ * // Later: await sov.push.unregister()
+ * ```
+ *
+ * `register()` asks for notification permission, subscribes with the project's public key
+ * (`GET /api/v1/push/webpush-key`) and registers the subscription as the signed-in user's push device
+ * (`platform: web`, `provider: webpush`). Sends from the console, `sov push send` or messaging reach it like any
+ * phone; `link` in a send opens that URL on click.
+ */
+export interface WebPushRegisterOptions {
+    /** Path of the service worker that shows notifications (default `/sovaria-sw.js`). */
+    serviceWorker?: string;
+    /** Use a registration you already have instead of registering `serviceWorker`. */
+    registration?: ServiceWorkerRegistration;
+    topics?: string[];
+    deviceId?: string;
+}
+type Requester = <T>(method: string, path: string, options?: {
+    body?: unknown;
+    requiresScope?: boolean;
+}) => Promise<T>;
+export declare class WebPushClient {
+    private readonly request;
+    constructor(request: Requester);
+    /** Whether this browser can receive web push. */
+    get supported(): boolean;
+    /** Subscribe this browser and register it for the signed-in user. Returns the device row. */
+    register(options?: WebPushRegisterOptions): Promise<Record<string, unknown>>;
+    /** Unsubscribe this browser and remove its push device. */
+    unregister(registration?: ServiceWorkerRegistration): Promise<number>;
+}
+export declare function urlBase64ToUint8Array(base64: string): Uint8Array;
+/**
+ * The service worker that shows Sovaria pushes and opens `link` on click. Serve it as `/sovaria-sw.js`, or
+ * `importScripts('/sovaria-sw.js')` from your own worker. Payload: `{title, body, image?, link?, tag?, data?}`.
+ */
+export declare const serviceWorkerSource = "/* Sovaria web push service worker */\nself.addEventListener('push', (event) => {\n  let p = {}\n  try { p = event.data ? event.data.json() : {} } catch (e) { p = { title: event.data && event.data.text() } }\n  const options = { body: p.body || '', image: p.image, icon: p.icon, tag: p.tag, data: { link: p.link, data: p.data || {} } }\n  event.waitUntil(self.registration.showNotification(p.title || 'Notification', options))\n})\nself.addEventListener('notificationclick', (event) => {\n  event.notification.close()\n  const link = event.notification.data && event.notification.data.link\n  if (!link) return\n  event.waitUntil(self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then((wins) => {\n    const url = new URL(link, self.location.origin).href\n    for (const w of wins) if (w.url === url && 'focus' in w) return w.focus()\n    return self.clients.openWindow(url)\n  }))\n})\n";
+export {};

package/dist/webpush.js

@@ -0,0 +1,99 @@
+/**
+ * Web push for browsers (Chrome, Edge, Firefox, Safari 16.4+ including iOS home-screen web apps), with the project's
+ * own VAPID keys — no Firebase project needed.
+ *
+ * ```ts
+ * // 1. Serve the service worker at your site's root: copy `serviceWorkerSource` into /sovaria-sw.js
+ * //    (or importScripts it from your own worker).
+ * // 2. After the user signs in, from a click handler (browsers require a user gesture):
+ * await sov.push.register({ topics: ['news'] })
+ * // Later: await sov.push.unregister()
+ * ```
+ *
+ * `register()` asks for notification permission, subscribes with the project's public key
+ * (`GET /api/v1/push/webpush-key`) and registers the subscription as the signed-in user's push device
+ * (`platform: web`, `provider: webpush`). Sends from the console, `sov push send` or messaging reach it like any
+ * phone; `link` in a send opens that URL on click.
+ */
+export class WebPushClient {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** Whether this browser can receive web push. */
+    get supported() {
+        const g = globalThis;
+        return Boolean(g.navigator?.serviceWorker && g.PushManager && g.Notification);
+    }
+    /** Subscribe this browser and register it for the signed-in user. Returns the device row. */
+    async register(options = {}) {
+        const g = globalThis;
+        if (!this.supported)
+            throw new Error('This browser does not support web push');
+        const permission = g.Notification.permission === 'granted' ? 'granted' : await g.Notification.requestPermission();
+        if (permission !== 'granted')
+            throw new Error('Notifications were not allowed');
+        const { public_key: publicKey } = await this.request('GET', '/api/v1/push/webpush-key', { requiresScope: false });
+        const registration = options.registration ?? (await g.navigator.serviceWorker.register(options.serviceWorker ?? '/sovaria-sw.js'));
+        let subscription = await registration.pushManager.getSubscription();
+        const key = urlBase64ToUint8Array(publicKey);
+        if (subscription && !sameKey(subscription.options?.applicationServerKey ?? null, key)) {
+            await subscription.unsubscribe(); // the project rotated its keys
+            subscription = null;
+        }
+        subscription ??= await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: key });
+        return this.request('POST', '/api/v1/push/devices', {
+            requiresScope: false,
+            body: { token: JSON.stringify(subscription), platform: 'web', provider: 'webpush', topics: options.topics,
+                device_id: options.deviceId, locale: g.navigator?.language },
+        });
+    }
+    /** Unsubscribe this browser and remove its push device. */
+    async unregister(registration) {
+        const g = globalThis;
+        const reg = registration ?? (await g.navigator?.serviceWorker?.getRegistration?.());
+        const subscription = await reg?.pushManager.getSubscription();
+        if (!subscription)
+            return 0;
+        const token = JSON.stringify(subscription);
+        await subscription.unsubscribe();
+        const out = await this.request('POST', '/api/v1/push/devices/unregister', { body: { token }, requiresScope: false });
+        return out.removed ?? 0;
+    }
+}
+export function urlBase64ToUint8Array(base64) {
+    const padded = (base64 + '='.repeat((4 - (base64.length % 4)) % 4)).replace(/-/g, '+').replace(/_/g, '/');
+    const raw = atob(padded);
+    const out = new Uint8Array(raw.length);
+    for (let i = 0; i < raw.length; i++)
+        out[i] = raw.charCodeAt(i);
+    return out;
+}
+function sameKey(a, b) {
+    if (!a)
+        return false;
+    const x = new Uint8Array(a);
+    return x.length === b.length && x.every((v, i) => v === b[i]);
+}
+/**
+ * The service worker that shows Sovaria pushes and opens `link` on click. Serve it as `/sovaria-sw.js`, or
+ * `importScripts('/sovaria-sw.js')` from your own worker. Payload: `{title, body, image?, link?, tag?, data?}`.
+ */
+export const serviceWorkerSource = `/* Sovaria web push service worker */
+self.addEventListener('push', (event) => {
+  let p = {}
+  try { p = event.data ? event.data.json() : {} } catch (e) { p = { title: event.data && event.data.text() } }
+  const options = { body: p.body || '', image: p.image, icon: p.icon, tag: p.tag, data: { link: p.link, data: p.data || {} } }
+  event.waitUntil(self.registration.showNotification(p.title || 'Notification', options))
+})
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close()
+  const link = event.notification.data && event.notification.data.link
+  if (!link) return
+  event.waitUntil(self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then((wins) => {
+    const url = new URL(link, self.location.origin).href
+    for (const w of wins) if (w.url === url && 'focus' in w) return w.focus()
+    return self.clients.openWindow(url)
+  }))
+})
+`;

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@sovaria/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Official JavaScript/TypeScript SDK for Sovaria: database (SQL and documents), auth, storage, realtime, functions and the full Sovaria API",
+  "keywords": [
+    "sovaria",
+    "sdk",
+    "baas",
+    "backend",
+    "database",
+    "postgres",
+    "auth",
+    "storage",
+    "realtime",
+    "firestore",
+    "supabase-alternative",
+    "firebase-alternative"
+  ],
+  "homepage": "https://sovaria.in/docs/javascript-setup",
+  "bugs": {
+    "url": "https://sovaria.in/contact"
+  },
+  "license": "MIT",
+  "author": "Sovaria (https://sovaria.in)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "firestore": [
+        "./dist/firestore.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./firestore": {
+      "types": "./dist/firestore.d.ts",
+      "import": "./dist/firestore.js",
+      "default": "./dist/firestore.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run src",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "docs:api": "typedoc --options typedoc.json",
+    "prepublishOnly": "npm run build && npm test -- --maxWorkers=2"
+  },
+  "dependencies": {
+    "hash-wasm": "4.12.0"
+  },
+  "devDependencies": {
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}