@zuzjs/flare-admin 0.1.1

package/dist/types/index.d.ts

@@ -0,0 +1,275 @@
+export interface FlareAdminConfig {
+    /**
+     * Base URL of your FlareServer instance.
+     * Self-hosted:  "http://localhost:5050"
+     * SaaS:         "https://www.zedgon.io"
+     */
+    serverUrl: string;
+    /** The app ID created with `flare app create` */
+    appId: string;
+    /**
+     * Admin key printed when you run `flare app create`.
+     * Keep in an environment variable — NEVER expose to the browser.
+     */
+    adminKey: string;
+    /** Default token TTL, e.g. "24h" */
+    defaultTtl?: string;
+}
+export interface CreateCustomTokenOptions {
+    role?: "user" | "admin" | "anon";
+    claims?: Record<string, unknown>;
+    ttl?: string;
+}
+export interface FlareAdminAuth {
+    createCustomToken(uid: string | number, opts?: CreateCustomTokenOptions): Promise<string>;
+}
+export interface AdminPushSendInput {
+    title?: string;
+    body?: string;
+    image?: string;
+    data?: Record<string, unknown>;
+    tokens?: string[];
+    uid?: string;
+    topic?: string;
+    priority?: "normal" | "high";
+    ttlSeconds?: number;
+    dryRun?: boolean;
+}
+export interface AdminPushSendResult {
+    sent: boolean;
+    appId: string;
+    targetCount: number;
+    successCount: number;
+    failureCount: number;
+    invalidatedTokenCount: number;
+    dryRun: boolean;
+}
+export interface AdminPushToken {
+    token: string;
+    uid: string;
+    platform?: string;
+    deviceId?: string;
+    topics?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+    lastSeenAt?: string;
+}
+export interface FlareAdminNotifications {
+    send(input: AdminPushSendInput): Promise<AdminPushSendResult>;
+    tokens(): Promise<{
+        appId: string;
+        hasPushGateway: boolean;
+        total: number;
+        tokens: AdminPushToken[];
+    }>;
+}
+export type QueryOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "array-contains" | "array-contains-any" | "elem-match" | "like" | "not-like" | "contains" | "exists" | "not-exists";
+export interface WhereFilter {
+    field: string;
+    op: QueryOperator;
+    value: unknown;
+}
+/** OR group — matches if ANY inner filter matches */
+export interface OrFilter {
+    or: AnyFilter[];
+}
+/** AND group — matches only if ALL inner filters match */
+export interface AndFilter {
+    and: AnyFilter[];
+}
+export type AnyFilter = WhereFilter | OrFilter | AndFilter;
+/**
+ * ORM-style shorthand: `{ age: ">= 25", role: "admin" }`
+ */
+export type WhereCondition = Record<string, string | number | boolean | unknown[]>;
+export interface OrderByClause {
+    field: string;
+    dir?: "asc" | "desc";
+}
+export interface GroupByClause {
+    fields: string[];
+}
+export interface HavingClause {
+    field: string;
+    op: "==" | "!=" | "<" | "<=" | ">" | ">=";
+    value: number;
+}
+export interface CursorValue {
+    values: unknown[];
+}
+export type AggregateFunction = "count" | "sum" | "avg" | "min" | "max" | "distinct";
+export interface AggregateSpec {
+    fn: AggregateFunction;
+    field?: string;
+    alias?: string;
+}
+export interface JoinClause {
+    source: string;
+    target: string;
+    as: string;
+    single?: boolean;
+    where?: AnyFilter[];
+    orderBy?: OrderByClause[];
+    limit?: number;
+    offset?: number;
+    select?: string[];
+    joins?: NestedJoinClause[];
+}
+export interface NestedJoinClause extends JoinClause {
+    collection: string;
+}
+export interface StructuredJoinClause {
+    from: string;
+    localField: string;
+    foreignField: string;
+    as: string;
+    single?: boolean;
+    where?: AnyFilter[];
+    orderBy?: OrderByClause[];
+    limit?: number;
+    offset?: number;
+    select?: string[];
+    joins?: StructuredJoinClause[];
+}
+export interface VectorSearchClause {
+    field: string;
+    vector: number[];
+    k: number;
+    metric?: "cosine" | "euclidean" | "dotProduct";
+    minScore?: number;
+}
+/** Full structured query (mirrors client StructuredQuery / server StructuredQuery) */
+export interface StructuredQuery {
+    where?: AnyFilter[];
+    orderBy?: OrderByClause[];
+    limit?: number;
+    offset?: number;
+    startAt?: CursorValue;
+    startAfter?: CursorValue;
+    endAt?: CursorValue;
+    endBefore?: CursorValue;
+    aggregate?: AggregateSpec[];
+    groupBy?: GroupByClause;
+    having?: HavingClause[];
+    joins?: StructuredJoinClause[];
+    vectorSearch?: VectorSearchClause;
+    select?: string[];
+    distinctField?: string;
+}
+export interface AdminListOptions {
+    limit?: number;
+    skip?: number;
+    where?: WhereFilter[];
+}
+/** Minimal structural interface satisfied by AdminCollectionReference<T>. */
+export interface FlareAdminDb {
+    collection<T = Record<string, unknown>>(name: string): AdminCollectionShape<T>;
+}
+export interface AdminDocumentShape<T> {
+    get(): Promise<T | null>;
+    set(data: Partial<T>): Promise<void>;
+    update(data: Partial<T>): Promise<void>;
+    delete(): Promise<void>;
+}
+export interface AdminCollectionShape<T> {
+    allowSensitiveAuthUserFields(enabled?: boolean): AdminCollectionShape<T>;
+    where(condition: WhereCondition): AdminCollectionShape<T>;
+    and(condition: WhereCondition): AdminCollectionShape<T>;
+    or(condition: WhereCondition): AdminCollectionShape<T>;
+    in(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    andIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    orIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    notIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    andNotIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    orNotIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    arrayContains(field: string, value: unknown): AdminCollectionShape<T>;
+    andArrayContains(field: string, value: unknown): AdminCollectionShape<T>;
+    orArrayContains(field: string, value: unknown): AdminCollectionShape<T>;
+    arrayContainsAny(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    andArrayContainsAny(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    orArrayContainsAny(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    some(field: string, condition: Record<string, unknown>): AdminCollectionShape<T>;
+    andSome(field: string, condition: Record<string, unknown>): AdminCollectionShape<T>;
+    orSome(field: string, condition: Record<string, unknown>): AdminCollectionShape<T>;
+    like(field: string, value: string): AdminCollectionShape<T>;
+    andLike(field: string, value: string): AdminCollectionShape<T>;
+    orLike(field: string, value: string): AdminCollectionShape<T>;
+    notLike(field: string, value: string): AdminCollectionShape<T>;
+    andNotLike(field: string, value: string): AdminCollectionShape<T>;
+    orNotLike(field: string, value: string): AdminCollectionShape<T>;
+    exists(field: string): AdminCollectionShape<T>;
+    andExists(field: string): AdminCollectionShape<T>;
+    orExists(field: string): AdminCollectionShape<T>;
+    notExists(field: string): AdminCollectionShape<T>;
+    andNotExists(field: string): AdminCollectionShape<T>;
+    orNotExists(field: string): AdminCollectionShape<T>;
+    latest(): AdminCollectionShape<T>;
+    newest(): AdminCollectionShape<T>;
+    oldest(): AdminCollectionShape<T>;
+    orderBy(field: string, dir?: "asc" | "desc"): AdminCollectionShape<T>;
+    limit(n: number): AdminCollectionShape<T>;
+    offset(n: number): AdminCollectionShape<T>;
+    startAt(...values: unknown[]): AdminCollectionShape<T>;
+    startAfter(...values: unknown[]): AdminCollectionShape<T>;
+    endAt(...values: unknown[]): AdminCollectionShape<T>;
+    endBefore(...values: unknown[]): AdminCollectionShape<T>;
+    aggregate(...specs: AggregateSpec[]): AdminCollectionShape<T>;
+    count(alias?: string): AdminCollectionShape<T>;
+    sum(field: string, alias?: string): AdminCollectionShape<T>;
+    avg(field: string, alias?: string): AdminCollectionShape<T>;
+    min(field: string, alias?: string): AdminCollectionShape<T>;
+    max(field: string, alias?: string): AdminCollectionShape<T>;
+    distinct(field: string, alias?: string): AdminCollectionShape<T>;
+    groupBy(...fields: string[]): AdminCollectionShape<T>;
+    having(field: string, op: HavingClause["op"], value: number): AdminCollectionShape<T>;
+    join(collection: string, j: JoinClause): AdminCollectionShape<T>;
+    joinNested(parentAlias: string, collection: string, j: JoinClause): AdminCollectionShape<T>;
+    Join(collection: string, j: JoinClause): AdminCollectionShape<T>;
+    JoinNested(parentAlias: string, collection: string, j: JoinClause): AdminCollectionShape<T>;
+    withRelation(relation: string, options?: Omit<JoinClause, "source" | "target" | "as"> & {
+        as?: string;
+    }): AdminCollectionShape<T>;
+    select(...fields: string[]): AdminCollectionShape<T>;
+    distinctField(field: string): AdminCollectionShape<T>;
+    vectorSearch(opts: VectorSearchClause): AdminCollectionShape<T>;
+    getRawQuery(): {
+        collection: string;
+        query: StructuredQuery;
+    };
+    get(): Promise<T[]>;
+    first(): Promise<T | null>;
+    last(): Promise<T | null>;
+    add(data: Partial<T>): Promise<AdminDocumentShape<T>>;
+    deleteMany(): Promise<number>;
+    doc(id: string): AdminDocumentShape<T>;
+}
+export interface AdminSnapshotData<T = unknown> {
+    subscriptionId: string;
+    collection: string;
+    docId?: string;
+    data: T;
+    type: "snapshot" | "change";
+    operation?: "insert" | "update" | "delete" | "replace";
+}
+export type AdminSnapshotCallback<T = unknown> = (data: AdminSnapshotData<T>) => void;
+export type AdminDocAddedCallback<T = unknown> = (data: T, docId: string) => void;
+export type AdminDocUpdatedCallback<T = unknown> = (data: T, docId: string) => void;
+export type AdminDocDeletedCallback = (docId: string) => void;
+export type AdminDocChangedCallback<T = unknown> = (data: T | null, docId: string, operation: "insert" | "update" | "delete" | "replace") => void;
+export interface AdminSubscribeOptions {
+    skipSnapshot?: boolean;
+}
+export interface AdminSubscriptionError {
+    code?: string;
+    message: string;
+    permissionDenied: boolean;
+    raw?: unknown;
+}
+export type AdminSubscriptionErrorCallback = (error: AdminSubscriptionError) => void;
+export interface AdminSubscriptionHandle {
+    (): void;
+    unsubscribe: () => void;
+    onError: (callback: AdminSubscriptionErrorCallback) => AdminSubscriptionHandle;
+    onPermissionDenied: (callback: AdminSubscriptionErrorCallback) => AdminSubscriptionHandle;
+    catch: (callback: AdminSubscriptionErrorCallback) => AdminSubscriptionHandle;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@zuzjs/flare-admin",
+  "version": "0.1.1",
+  "description": "Server-side admin SDK for FlareServer — mint custom auth tokens from your backend (like firebase-admin)",
+  "keywords": [
+    "flare",
+    "flare-admin",
+    "zuzjs",
+    "auth",
+    "realtime",
+    "websocket"
+  ],
+  "author": "Zuz.js Team <support@zuz.com.pk>",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zuzjs/flare-admin.git"
+  },
+  "homepage": "https://www.zedgon.io",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "ws": "^8.19.0"
+  }
+}