@edge-base/admin 0.1.1

package/README.md

@@ -0,0 +1,213 @@
+<h1 align="center">@edge-base/admin</h1>
+
+<p align="center">
+  <b>Trusted server-side SDK for EdgeBase</b><br>
+  Database admin, user management, SQL, analytics, push, storage, and function calls from secure environments
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@edge-base/admin"><img src="https://img.shields.io/npm/v/%40edge-base%2Fadmin?color=brightgreen" alt="npm"></a>&nbsp;
+  <a href="https://edgebase.fun/docs/database/admin-sdk"><img src="https://img.shields.io/badge/docs-admin_sdk-blue" alt="Docs"></a>&nbsp;
+  <a href="https://github.com/edge-base/edgebase/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  Node.js · Edge runtimes · Server actions · Background jobs · Trusted workers
+</p>
+
+<p align="center">
+  <a href="https://edgebase.fun/docs/database/admin-sdk"><b>Database Admin SDK</b></a> ·
+  <a href="https://edgebase.fun/docs/authentication/admin-users"><b>Admin Users</b></a> ·
+  <a href="https://edgebase.fun/docs/push/admin-sdk"><b>Push Admin SDK</b></a> ·
+  <a href="https://edgebase.fun/docs/analytics/admin-sdk"><b>Analytics Admin SDK</b></a>
+</p>
+
+---
+
+`@edge-base/admin` is the trusted server-side SDK for EdgeBase.
+
+Use it when you need:
+
+- Service Key authenticated access
+- server-side database operations that bypass access rules
+- admin user management
+- raw SQL
+- push and analytics from secure environments
+- server-to-server function calls
+
+If code runs in a browser, use [`@edge-base/web`](https://www.npmjs.com/package/@edge-base/web) instead. If code runs on the server but should act as the current signed-in user through cookies, use [`@edge-base/ssr`](https://www.npmjs.com/package/@edge-base/ssr).
+
+> Beta: the package is already usable, but some APIs may still evolve before general availability.
+
+## Documentation Map
+
+- [Database Admin SDK](https://edgebase.fun/docs/database/admin-sdk)
+  Server-side database access with a Service Key
+- [Admin Users](https://edgebase.fun/docs/authentication/admin-users)
+  Create, update, list, revoke, and manage users
+- [Push Admin SDK](https://edgebase.fun/docs/push/admin-sdk)
+  Send push notifications from secure environments
+- [Analytics Admin SDK](https://edgebase.fun/docs/analytics/admin-sdk)
+  Query request analytics and track server-side events
+- [Admin SDK Reference](https://edgebase.fun/docs/admin-sdk/reference)
+  Public admin SDK surface by category
+
+## For AI Coding Assistants
+
+This package ships with an `llms.txt` file for AI-assisted server SDK usage.
+
+You can find it:
+
+- after install: `node_modules/@edge-base/admin/llms.txt`
+- in the repository: [llms.txt](https://github.com/edge-base/edgebase/blob/main/packages/sdk/js/packages/admin/llms.txt)
+
+Use it when you want an agent to:
+
+- keep Service Key logic on the server
+- choose between `web`, `ssr`, and `admin`
+- use the correct `db(namespace, id?)` and `sql(...)` signatures
+- avoid shipping privileged SDK code to the browser
+
+## Installation
+
+```bash
+npm install @edge-base/admin
+```
+
+## Quick Start
+
+```ts
+import { createAdminClient } from '@edge-base/admin';
+
+const admin = createAdminClient(process.env.EDGEBASE_URL!, {
+  serviceKey: process.env.EDGEBASE_SERVICE_KEY,
+});
+
+const { items: posts } = await admin
+  .db('app')
+  .table('posts')
+  .orderBy('createdAt', 'desc')
+  .limit(20)
+  .getList();
+
+console.log(posts);
+```
+
+Inside EdgeBase App Functions, you can also rely on environment detection:
+
+```ts
+import { createAdminClient } from '@edge-base/admin';
+
+const admin = createAdminClient();
+```
+
+## Core API
+
+Once you create an admin client, these are the main surfaces you will use:
+
+- `admin.db(namespace, id?)`
+  Server-side database access
+- `admin.auth`
+  Admin user management
+- `admin.sql(...)`
+  Raw SQL execution
+- `admin.storage`
+  Server-side storage access
+- `admin.functions`
+  Call app functions from trusted code
+- `admin.push`
+  Send push notifications
+- `admin.analytics`
+  Query analytics and track server-side events
+- `admin.kv(namespace)`, `admin.d1(database)`, `admin.vector(index)`
+  Access platform resources from trusted code
+
+## Database Access
+
+```ts
+type Post = {
+  id: string;
+  title: string;
+  status: 'draft' | 'published';
+};
+
+const posts = admin.db('app').table<Post>('posts');
+
+const result = await posts
+  .where('status', '==', 'published')
+  .orderBy('title', 'asc')
+  .limit(50)
+  .getList();
+```
+
+For instance databases, pass the instance id positionally:
+
+```ts
+admin.db('workspace', 'ws-123');
+admin.db('user', 'user-123');
+```
+
+Read more: [Database Admin SDK](https://edgebase.fun/docs/database/admin-sdk)
+
+## Admin Auth
+
+```ts
+const created = await admin.auth.createUser({
+  email: 'june@example.com',
+  password: 'secure-pass-123',
+  displayName: 'June',
+});
+
+await admin.auth.setCustomClaims(created.id, {
+  role: 'moderator',
+});
+
+const users = await admin.auth.listUsers({ limit: 20 });
+console.log(users.users);
+```
+
+Read more: [Admin Users](https://edgebase.fun/docs/authentication/admin-users)
+
+## Raw SQL
+
+`sql()` supports two forms:
+
+```ts
+const health = await admin.sql('select 1 as ok');
+
+const docs = await admin.sql(
+  'workspace',
+  'ws-123',
+  'select * from documents where status = ?',
+  ['published'],
+);
+```
+
+## Push And Analytics
+
+```ts
+await admin.push.send('user-123', {
+  title: 'Deployment finished',
+  body: 'Your content is live.',
+});
+
+const overview = await admin.analytics.overview({ range: '7d' });
+console.log(overview.summary.totalRequests);
+```
+
+Read more:
+
+- [Push Admin SDK](https://edgebase.fun/docs/push/admin-sdk)
+- [Analytics Admin SDK](https://edgebase.fun/docs/analytics/admin-sdk)
+
+## Choose The Right Package
+
+| Package | Use it for |
+| --- | --- |
+| `@edge-base/web` | Browser and untrusted client code |
+| `@edge-base/ssr` | Server-side code acting as the current cookie-authenticated user |
+| `@edge-base/admin` | Trusted server-side code with Service Key access |
+
+## License
+
+MIT

package/dist/admin-auth.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Admin Auth client for server-side user management
+ *: admin.auth context — Service Key required
+ *: Service Key
+ */
+import type { HttpClient } from '@edge-base/core';
+export interface UserRecord {
+    id: string;
+    email?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    role?: string;
+    emailVisibility?: string;
+    isAnonymous?: boolean;
+    customClaims?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ListUsersResult {
+    users: UserRecord[];
+    cursor?: string;
+}
+export interface CreateUserOptions {
+    email: string;
+    password: string;
+    displayName?: string;
+    role?: string;
+    /** Preferred locale for this user (e.g. 'ko', 'ja'). Default: 'en' */
+    locale?: string;
+}
+export interface UpdateUserOptions {
+    email?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    role?: string;
+    emailVisibility?: string;
+    /** Preferred locale for this user (e.g. 'ko', 'ja'). */
+    locale?: string;
+}
+export declare class AdminAuthClient {
+    private client;
+    private hasServiceKey;
+    private adminCore;
+    constructor(client: HttpClient, hasServiceKey: boolean);
+    /** Ensure Service Key is configured */
+    private requireServiceKey;
+    /** Get a user by ID */
+    getUser(userId: string): Promise<UserRecord>;
+    /** List users with pagination */
+    listUsers(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListUsersResult>;
+    /** Create a new user (server-side registration) */
+    createUser(data: CreateUserOptions): Promise<UserRecord>;
+    /** Update a user */
+    updateUser(userId: string, data: UpdateUserOptions): Promise<UserRecord>;
+    /** Delete a user */
+    deleteUser(userId: string): Promise<void>;
+    /** Set custom claims for a user (reflected in JWT on next token refresh) */
+    setCustomClaims(userId: string, claims: Record<string, unknown>): Promise<void>;
+    /** Revoke all sessions for a user (force re-authentication) */
+    revokeAllSessions(userId: string): Promise<void>;
+}
+//# sourceMappingURL=admin-auth.d.ts.map

package/dist/admin-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-auth.d.ts","sourceRoot":"","sources":["../src/admin-auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,eAAe;IAKxB,OAAO,CAAC,MAAM;IAJhB,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,SAAS,CAAkB;gBAGzB,MAAM,EAAE,UAAU,EAC1B,aAAa,EAAE,OAAO;IAMxB,uCAAuC;IACvC,OAAO,CAAC,iBAAiB;IASzB,uBAAuB;IACjB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAMlD,iCAAiC;IAC3B,SAAS,CAAC,OAAO,CAAC,EAAE;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,eAAe,CAAC;IAQ5B,mDAAmD;IAC7C,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IAM9D,oBAAoB;IACd,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IAM9E,oBAAoB;IACd,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/C,4EAA4E;IACtE,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC;IAKhB,+DAA+D;IACzD,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIvD"}

package/dist/admin-auth.js

@@ -0,0 +1,67 @@
+/**
+ * Admin Auth client for server-side user management
+ *: admin.auth context — Service Key required
+ *: Service Key
+ */
+import { EdgeBaseError, HttpClientAdapter } from '@edge-base/core';
+import { DefaultAdminApi } from './generated/admin-api-core.js';
+export class AdminAuthClient {
+    client;
+    hasServiceKey;
+    adminCore;
+    constructor(client, hasServiceKey) {
+        this.client = client;
+        this.hasServiceKey = hasServiceKey;
+        this.adminCore = new DefaultAdminApi(new HttpClientAdapter(client));
+    }
+    /** Ensure Service Key is configured */
+    requireServiceKey() {
+        if (!this.hasServiceKey) {
+            throw new EdgeBaseError(403, 'admin.auth requires serviceKey. Initialize EdgeBase with { serviceKey: "..." } option.');
+        }
+    }
+    /** Get a user by ID */
+    async getUser(userId) {
+        this.requireServiceKey();
+        const result = await this.adminCore.adminAuthGetUser(userId);
+        return result.user ?? result;
+    }
+    /** List users with pagination */
+    async listUsers(options) {
+        this.requireServiceKey();
+        const query = {};
+        if (options?.limit)
+            query.limit = String(options.limit);
+        if (options?.cursor)
+            query.cursor = options.cursor;
+        return this.adminCore.adminAuthListUsers(query);
+    }
+    /** Create a new user (server-side registration) */
+    async createUser(data) {
+        this.requireServiceKey();
+        const result = await this.adminCore.adminAuthCreateUser(data);
+        return result.user ?? result;
+    }
+    /** Update a user */
+    async updateUser(userId, data) {
+        this.requireServiceKey();
+        const result = await this.adminCore.adminAuthUpdateUser(userId, data);
+        return result.user ?? result;
+    }
+    /** Delete a user */
+    async deleteUser(userId) {
+        this.requireServiceKey();
+        await this.adminCore.adminAuthDeleteUser(userId);
+    }
+    /** Set custom claims for a user (reflected in JWT on next token refresh) */
+    async setCustomClaims(userId, claims) {
+        this.requireServiceKey();
+        await this.adminCore.adminAuthSetClaims(userId, claims);
+    }
+    /** Revoke all sessions for a user (force re-authentication) */
+    async revokeAllSessions(userId) {
+        this.requireServiceKey();
+        await this.adminCore.adminAuthRevokeUserSessions(userId);
+    }
+}
+//# sourceMappingURL=admin-auth.js.map

package/dist/admin-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-auth.js","sourceRoot":"","sources":["../src/admin-auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAuChE,MAAM,OAAO,eAAe;IAKhB;IAJF,aAAa,CAAU;IACvB,SAAS,CAAkB;IAEnC,YACU,MAAkB,EAC1B,aAAsB;QADd,WAAM,GAAN,MAAM,CAAY;QAG1B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,uCAAuC;IAC/B,iBAAiB;QACvB,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,aAAa,CACrB,GAAG,EACH,wFAAwF,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,KAAK,CAAC,OAAO,CAAC,MAAc;QAC1B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,MAAM,CAAyB,CAAC;QACrF,OAAQ,MAAc,CAAC,IAAI,IAAI,MAAM,CAAC;IACxC,CAAC;IAED,iCAAiC;IACjC,KAAK,CAAC,SAAS,CAAC,OAGf;QACC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,KAAK,GAA2B,EAAE,CAAC;QACzC,IAAI,OAAO,EAAE,KAAK;YAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACxD,IAAI,OAAO,EAAE,MAAM;YAAE,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QACnD,OAAO,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAA6B,CAAC;IAC9E,CAAC;IAED,mDAAmD;IACnD,KAAK,CAAC,UAAU,CAAC,IAAuB;QACtC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC,IAAI,CAAyB,CAAC;QACtF,OAAQ,MAAc,CAAC,IAAI,IAAI,MAAM,CAAC;IACxC,CAAC;IAED,oBAAoB;IACpB,KAAK,CAAC,UAAU,CAAC,MAAc,EAAE,IAAuB;QACtD,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAyB,CAAC;QAC9F,OAAQ,MAAc,CAAC,IAAI,IAAI,MAAM,CAAC;IACxC,CAAC;IAED,oBAAoB;IACpB,KAAK,CAAC,UAAU,CAAC,MAAc;QAC7B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,eAAe,CACnB,MAAc,EACd,MAA+B;QAE/B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,iBAAiB,CAAC,MAAc;QACpC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,SAAS,CAAC,2BAA2B,CAAC,MAAM,CAAC,CAAC;IAC3D,CAAC;CACF"}

package/dist/analytics.d.ts

@@ -0,0 +1,200 @@
+/**
+ * AnalyticsClient — Analytics query + custom event tracking for Admin/Server SDK
+ *
+ * Feature 1: Request log metrics query (same data as admin dashboard)
+ * Feature 2: Custom event tracking (server-side) + query
+ *
+ * Usage:
+ *   const admin = createAdminClient(url, { serviceKey });
+ *
+ *   // Request log metrics
+ *   const overview = await admin.analytics.overview({ range: '7d' });
+ *   const ts = await admin.analytics.timeSeries({ range: '24h', category: 'db' });
+ *
+ *   // Custom events
+ *   await admin.analytics.track('user_upgraded', { plan: 'pro', amount: 29.99 }, 'user-123');
+ *   const events = await admin.analytics.queryEvents({ event: 'user_upgraded', metric: 'count' });
+ */
+import type { HttpClient } from '@edge-base/core';
+/** Options for querying request log metrics. */
+export interface AnalyticsQueryOptions {
+    /** Time range for the query. */
+    range?: '1h' | '6h' | '24h' | '7d' | '30d' | '90d';
+    /** Filter by route category (e.g. 'db', 'auth', 'storage'). */
+    category?: string;
+    /** Grouping interval for time series data. */
+    groupBy?: 'minute' | 'hour' | 'day';
+}
+/** A single point in a time series. */
+export interface TimeSeriesPoint {
+    timestamp: number;
+    requests: number;
+    errors: number;
+    avgLatency: number;
+    uniqueUsers: number;
+}
+/** Aggregate summary of request metrics. */
+export interface AnalyticsSummary {
+    totalRequests: number;
+    totalErrors: number;
+    avgLatency: number;
+    uniqueUsers: number;
+}
+/** Breakdown item (e.g. by category or status code). */
+export interface BreakdownItem {
+    label: string;
+    count: number;
+    percentage: number;
+    avgLatency?: number;
+    errorRate?: number;
+}
+/** Top endpoint/item entry. */
+export interface TopItem {
+    label: string;
+    count: number;
+    avgLatency: number;
+    errorRate: number;
+}
+/** Full overview response from the analytics query endpoint. */
+export interface AnalyticsOverview {
+    timeSeries: TimeSeriesPoint[];
+    summary: AnalyticsSummary;
+    breakdown: BreakdownItem[];
+    topItems: TopItem[];
+}
+/** Data for tracking a single custom event. */
+export interface TrackEventData {
+    /** Event name (required). */
+    name: string;
+    /** Arbitrary properties (max 50 keys, max 4KB JSON). */
+    properties?: Record<string, string | number | boolean>;
+    /** Unix timestamp in ms (default: now). */
+    timestamp?: number;
+    /** User ID override (Service Key only — ignored with JWT). */
+    userId?: string;
+}
+/** Options for querying custom events. */
+export interface EventQueryOptions {
+    /** Time range. */
+    range?: '1h' | '6h' | '24h' | '7d' | '30d' | '90d';
+    /** Filter by event name. */
+    event?: string;
+    /** Filter by user ID. */
+    userId?: string;
+    /** Query metric type. */
+    metric?: 'list' | 'count' | 'timeSeries' | 'topEvents';
+    /** Grouping interval for time series. */
+    groupBy?: 'minute' | 'hour' | 'day';
+    /** Max results (for list metric). */
+    limit?: number;
+    /** Cursor for pagination (for list metric). */
+    cursor?: string;
+}
+/** A single custom event record. */
+export interface EventItem {
+    id: number;
+    timestamp: number;
+    userId: string | null;
+    eventName: string;
+    properties: Record<string, unknown> | null;
+}
+/** Result for metric='list'. */
+export interface EventListResult {
+    events: EventItem[];
+    cursor?: string;
+    hasMore: boolean;
+}
+/** Result for metric='count'. */
+export interface EventCountResult {
+    totalEvents: number;
+    uniqueUsers: number;
+}
+/** Result for metric='timeSeries'. */
+export interface EventTimeSeriesResult {
+    timeSeries: Array<{
+        timestamp: number;
+        count: number;
+    }>;
+}
+/** Result for metric='topEvents'. */
+export interface EventTopResult {
+    topEvents: Array<{
+        eventName: string;
+        count: number;
+        uniqueUsers: number;
+    }>;
+}
+export declare class AnalyticsClient {
+    private core;
+    private adminCore;
+    constructor(httpClient: HttpClient);
+    /**
+     * Get a full analytics overview (time series + summary + breakdown + top endpoints).
+     *
+     * @example
+     * const overview = await admin.analytics.overview({ range: '7d' });
+     * console.log(overview.summary.totalRequests);
+     */
+    overview(options?: AnalyticsQueryOptions): Promise<AnalyticsOverview>;
+    /**
+     * Get time series data only.
+     *
+     * @example
+     * const ts = await admin.analytics.timeSeries({ range: '24h', category: 'db' });
+     */
+    timeSeries(options?: AnalyticsQueryOptions): Promise<TimeSeriesPoint[]>;
+    /**
+     * Get breakdown data (by category, status code, etc.).
+     *
+     * @example
+     * const breakdown = await admin.analytics.breakdown({ range: '30d' });
+     */
+    breakdown(options?: AnalyticsQueryOptions): Promise<BreakdownItem[]>;
+    /**
+     * Get top endpoints by request count.
+     *
+     * @example
+     * const top = await admin.analytics.topEndpoints({ range: '7d', category: 'auth' });
+     */
+    topEndpoints(options?: AnalyticsQueryOptions): Promise<TopItem[]>;
+    /**
+     * Track a single custom event.
+     *
+     * @param name       Event name (e.g. 'user_upgraded')
+     * @param properties Arbitrary key-value data (max 50 keys, max 4KB)
+     * @param userId     User ID to associate (Service Key callers only)
+     *
+     * @example
+     * await admin.analytics.track('user_upgraded', { plan: 'pro', amount: 29.99 }, 'user-123');
+     */
+    track(name: string, properties?: Record<string, string | number | boolean>, userId?: string): Promise<void>;
+    /**
+     * Track multiple custom events in a single request (max 100).
+     *
+     * @example
+     * await admin.analytics.trackBatch([
+     *   { name: 'page_view', properties: { path: '/pricing' } },
+     *   { name: 'page_view', properties: { path: '/docs' } },
+     * ]);
+     */
+    trackBatch(events: TrackEventData[]): Promise<void>;
+    /**
+     * Query custom events. Returns different shapes based on `metric`.
+     *
+     * @example
+     * // List events
+     * const list = await admin.analytics.queryEvents({ event: 'purchase', metric: 'list', limit: 20 });
+     *
+     * // Count
+     * const count = await admin.analytics.queryEvents({ event: 'purchase', metric: 'count' });
+     *
+     * // Time series
+     * const ts = await admin.analytics.queryEvents({ metric: 'timeSeries', groupBy: 'day' });
+     *
+     * // Top events
+     * const top = await admin.analytics.queryEvents({ metric: 'topEvents' });
+     */
+    queryEvents<T = EventListResult | EventCountResult | EventTimeSeriesResult | EventTopResult>(options?: EventQueryOptions): Promise<T>;
+    private buildQuery;
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

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