@openmeter/sdk 1.0.0-beta.3 → 1.0.0-beta.31

package/README.md

@@ -3,7 +3,7 @@
 ## Install
 
 ```sh
-npm install --save @openmeter/sdk@beta
+npm install --save @openmeter/sdk
 ```
 
 ## Example
@@ -15,15 +15,15 @@ const openmeter = new OpenMeter({ baseUrl: 'http://localhost:8888' })
 
 // Ingesting an event
 const event: Event = {
-    specversion: '1.0',
-    id: 'id-1',
-    source: 'my-app',
-    type: 'my-type',
-    subject: 'my-awesome-user-id',
-    time: new Date(),
-    data: {
-        api_calls: 1,
-    },
+  specversion: '1.0',
+  id: 'id-1',
+  source: 'my-app',
+  type: 'my-type',
+  subject: 'my-awesome-user-id',
+  time: new Date(),
+  data: {
+    api_calls: 1,
+  },
 }
 await openmeter.events.ingest(event)
 
@@ -41,19 +41,27 @@ const meter = await openmeter.meters.get('m1')
 import { type Event } from '@openmeter/sdk'
 
 const event: Event = {
-    specversion: '1.0',
-    id: 'id-1',
-    source: 'my-app',
-    type: 'my-type',
-    subject: 'my-awesome-user-id',
-    time: new Date(),
-    data: {
-        api_calls: 1,
-    },
+  specversion: '1.0',
+  id: 'id-1',
+  source: 'my-app',
+  type: 'my-type',
+  subject: 'my-awesome-user-id',
+  time: new Date(),
+  data: {
+    api_calls: 1,
+  },
 }
 await openmeter.events.ingest(event)
 ```
 
+#### list
+
+Retrieve latest raw events. Useful for debugging.
+
+```ts
+const events = await openmeter.events.list()
+```
+
 ### Meters
 
 #### list
@@ -72,17 +80,100 @@ Get one meter by slug.
 const meter = await openmeter.meters.get('m1')
 ```
 
-#### values
+#### query
 
-Get back meter values.
+Query meter values.
 
 ```ts
 import { WindowSize } from '@openmeter/sdk'
 
-const values = await openmeter.meters.values('my-meter-slug', {
-    subject: 'user-1',
-    from: new Date('2021-01-01'),
-    to: new Date('2021-01-02'),
-    windowSize: WindowSize.HOUR
+const values = await openmeter.meters.query('my-meter-slug', {
+  subject: ['user-1'],
+  groupBy: ['method', 'path'],
+  from: new Date('2021-01-01'),
+  to: new Date('2021-01-02'),
+  windowSize: WindowSize.HOUR,
 })
 ```
+
+#### subjects
+
+List meter subjects.
+
+```ts
+const subjects = await openmeter.meters.subjects('my-meter-slug')
+```
+
+### Portal
+
+#### createToken
+
+Create subject specific tokens.
+Useful to build consumer dashboards.
+
+```ts
+const token = await openmeter.portal.createToken({ subject: 'customer-1' })
+```
+
+#### invalidateTokens
+
+Invalidate portal tokens for all or specific subjects.
+
+```ts
+await openmeter.portal.invalidateTokens()
+```
+
+## Helpers
+
+### Vercel AI SDK / Next.js
+
+The OpenAI streaming API used by the Vercel AI SDK doesn't return token usage metadata by default.
+The OpenMeter `createOpenAIStreamCallback` helper function decorates the callback with a `onUsage`
+callback which you can use to report usage to OpenMeter.
+
+```ts
+import OpenAI from 'openai'
+import { OpenAIStream, StreamingTextResponse } from 'ai'
+import { createOpenAIStreamCallback } from '@openmeter/sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const model = 'gpt-3.5-turbo'
+
+  const response = await openai.chat.completions.create({
+    model,
+    messages,
+    stream: true,
+  })
+
+  const streamCallbacks = await createOpenAIStreamCallback(
+    {
+      model,
+      prompts: messages.map(({ content }) => content),
+    },
+    {
+      // onToken() => {...}
+      // onFinal() => {...}
+      async onUsage(usage) {
+        try {
+          await openmeter.events.ingest({
+            source: 'my-app',
+            type: 'my-event-type',
+            subject: 'my-customer-id',
+            data: {
+              // Usage is { total_tokens, prompt_tokens, completion_tokens }
+              ...usage,
+              model,
+            },
+          })
+        } catch (err) {
+          console.error('failed to ingest usage', err)
+        }
+      },
+    }
+  )
+
+  const stream = OpenAIStream(response, streamCallbacks)
+  return new StreamingTextResponse(stream)
+}
+```

package/dist/clients/client.d.ts

@@ -18,7 +18,7 @@ export type Problem = components['schemas']['Problem'];
 export declare class BaseClient {
     protected config: OpenMeterConfig;
     constructor(config: OpenMeterConfig);
-    protected request<T>({ path, method, searchParams, headers, body, options }: {
+    protected request<T>({ path, method, searchParams, headers, body, options, }: {
         path: string;
         method: Dispatcher.HttpMethod;
         searchParams?: URLSearchParams;
@@ -28,12 +28,12 @@ export declare class BaseClient {
     }): Promise<T>;
     protected getUrl(path: string, searchParams?: URLSearchParams): import("url").URL;
     protected getAuthHeaders(): IncomingHttpHeaders;
-    protected static toURLSearchParams(params: Record<string, string | number | Date | string[]>): URLSearchParams;
+    protected static toURLSearchParams(params: Record<string, string | number | Date | string[] | undefined>): URLSearchParams;
 }
 export declare class HttpError extends Error {
     statusCode: number;
     problem?: Problem;
-    constructor({ statusCode, problem }: {
+    constructor({ statusCode, problem, }: {
         statusCode: number;
         problem?: Problem;
     });

package/dist/clients/client.js

@@ -4,7 +4,7 @@ export class BaseClient {
     constructor(config) {
         this.config = config;
     }
-    async request({ path, method, searchParams, headers, body, options }) {
+    async request({ path, method, searchParams, headers, body, options, }) {
         // Building URL
         const url = this.getUrl(path, searchParams);
         // Request options
@@ -17,7 +17,7 @@ export class BaseClient {
         };
         const reqOpts = {
             method,
-            headers: reqHeaders
+            headers: reqHeaders,
         };
         // Optional body
         if (body) {
@@ -30,7 +30,7 @@ export class BaseClient {
         // Error handling
         if (resp.statusCode > 399) {
             if (resp.headers['content-type'] === 'application/problem+json') {
-                const problem = await resp.body.json();
+                const problem = (await resp.body.json());
                 throw new HttpError({
                     statusCode: resp.statusCode,
                     problem,
@@ -46,7 +46,7 @@ export class BaseClient {
             return undefined;
         }
         if (resp.headers['content-type'] === 'application/json') {
-            return await resp.body.json();
+            return (await resp.body.json());
         }
         if (!resp.headers['content-type']) {
             throw new Error('Missing content type');
@@ -62,13 +62,13 @@ export class BaseClient {
     getAuthHeaders() {
         if (this.config.token) {
             return {
-                authorization: `Bearer ${this.config.token} `,
+                authorization: `Bearer ${this.config.token}`,
             };
         }
         if (this.config.username && this.config.password) {
-            const encoded = Buffer.from(`${this.config.username}:${this.config.password} `).toString('base64');
+            const encoded = Buffer.from(`${this.config.username}:${this.config.password}`).toString('base64');
             return {
-                authorization: `Basic ${encoded} `,
+                authorization: `Basic ${encoded}`,
             };
         }
         return {};
@@ -76,6 +76,9 @@ export class BaseClient {
     static toURLSearchParams(params) {
         const searchParams = new URLSearchParams();
         for (const [key, value] of Object.entries(params)) {
+            if (value === undefined) {
+                continue;
+            }
             if (Array.isArray(value)) {
                 searchParams.append(key, value.join(','));
             }
@@ -92,7 +95,7 @@ export class BaseClient {
 export class HttpError extends Error {
     statusCode;
     problem;
-    constructor({ statusCode, problem }) {
+    constructor({ statusCode, problem, }) {
         super(problem?.type || 'unexpected status code');
         this.name = 'HttpError';
         this.statusCode = statusCode;

package/dist/clients/event.d.ts

@@ -1,4 +1,14 @@
+import { components } from '../schemas/openapi.js';
 import { RequestOptions, BaseClient, OpenMeterConfig } from './client.js';
+type CloudEvents = components['schemas']['Event'];
+export type IngestedEvent = components['schemas']['IngestedEvent'];
+export type EventsQueryParams = {
+    /**
+     * @description Limit number of results. Max: 100
+     * @example 25
+     */
+    limit?: number;
+};
 /**
  * Usage Event
  */
@@ -62,4 +72,9 @@ export declare class EventsClient extends BaseClient {
      * @see https://cloudevents.io
      */
     ingest(usageEvent: Event, options?: RequestOptions): Promise<void>;
+    /**
+     * List raw events
+     */
+    list(params?: EventsQueryParams, options?: RequestOptions): Promise<CloudEvents[]>;
 }
+export {};

package/dist/clients/event.js

@@ -9,7 +9,8 @@ export class EventsClient extends BaseClient {
      * @see https://cloudevents.io
      */
     async ingest(usageEvent, options) {
-        if (usageEvent.datacontenttype && usageEvent.datacontenttype !== 'application/json') {
+        if (usageEvent.datacontenttype &&
+            usageEvent.datacontenttype !== 'application/json') {
             throw new TypeError(`Unsupported datacontenttype: ${usageEvent.datacontenttype}`);
         }
         // We default where we can to lower the barrier to use CloudEvents
@@ -22,7 +23,7 @@ export class EventsClient extends BaseClient {
             time: usageEvent.time?.toISOString(),
             datacontenttype: usageEvent.datacontenttype,
             dataschema: usageEvent.dataschema,
-            data: usageEvent.data
+            data: usageEvent.data,
         };
         // Making Request
         return await this.request({
@@ -32,7 +33,21 @@ export class EventsClient extends BaseClient {
             headers: {
                 'Content-Type': 'application/cloudevents+json',
             },
-            options
+            options,
+        });
+    }
+    /**
+     * List raw events
+     */
+    async list(params, options) {
+        const searchParams = params
+            ? BaseClient.toURLSearchParams(params)
+            : undefined;
+        return this.request({
+            method: 'GET',
+            path: `/api/v1/events`,
+            searchParams,
+            options,
         });
     }
 }

package/dist/clients/meter.d.ts

@@ -13,7 +13,11 @@ export declare enum MeterAggregation {
     MAX = "MAX"
 }
 export type MeterQueryParams = {
-    subject?: string;
+    /**
+     * @description Subject(s) to filter by.
+     * @example ["customer-1", "customer-2"]
+     */
+    subject?: string[];
     /**
      * @description Start date.
      * Must be aligned with the window size.
@@ -26,13 +30,24 @@ export type MeterQueryParams = {
      * Inclusive.
      */
     to?: Date;
-    /** @description If not specified, a single usage aggregate will be returned for the entirety of the specified period for each subject and group. */
+    /**
+     * @description Window Size
+     * If not specified, a single usage aggregate will be returned for the entirety of
+     * the specified period for each subject and group.
+     */
     windowSize?: WindowSizeType;
-    /** @description If not specified a single aggregate will be returned for each subject and time window. */
+    /**
+     * @description The value is the name of the time zone as defined in the IANA Time Zone Database (http://www.iana.org/time-zones).
+     * If not specified, the UTC timezone will be used.
+     */
+    windowTimeZone?: string;
+    /**
+     * @description Group By
+     * If not specified a single aggregate will be returned for each subject and time window.
+     */
     groupBy?: string[];
 };
-export type MeterQueryResponse = paths['/api/v1/meters/{meterIdOrSlug}/values']['get']['responses']['200']['content']['application/json'];
-export type MeterValue = components['schemas']['MeterValue'];
+export type MeterQueryResponse = paths['/api/v1/meters/{meterIdOrSlug}/query']['get']['responses']['200']['content']['application/json'];
 export type Meter = components['schemas']['Meter'];
 export type WindowSizeType = components['schemas']['WindowSize'];
 export declare class MetersClient extends BaseClient {
@@ -46,7 +61,11 @@ export declare class MetersClient extends BaseClient {
      */
     list(options?: RequestOptions): Promise<Meter[]>;
     /**
-     * Get aggregated values of a meter
+     * Query a meter
+     */
+    query(slug: string, params?: MeterQueryParams, options?: RequestOptions): Promise<MeterQueryResponse>;
+    /**
+     * List subjects of a meter
      */
-    values(slug: string, params?: MeterQueryParams, options?: RequestOptions): Promise<MeterQueryResponse>;
+    subjects(slug: string, options?: RequestOptions): Promise<string[]>;
 }

package/dist/clients/meter.js

@@ -38,15 +38,27 @@ export class MetersClient extends BaseClient {
         });
     }
     /**
-     * Get aggregated values of a meter
+     * Query a meter
      */
-    async values(slug, params, options) {
-        const searchParams = params ? BaseClient.toURLSearchParams(params) : undefined;
+    async query(slug, params, options) {
+        const searchParams = params
+            ? BaseClient.toURLSearchParams(params)
+            : undefined;
         return this.request({
             method: 'GET',
-            path: `/api/v1/meters/${slug}/values`,
+            path: `/api/v1/meters/${slug}/query`,
             searchParams,
             options,
         });
     }
+    /**
+     * List subjects of a meter
+     */
+    async subjects(slug, options) {
+        return this.request({
+            method: 'GET',
+            path: `/api/v1/meters/${slug}/subjects`,
+            options,
+        });
+    }
 }

package/dist/clients/portal.d.ts

@@ -0,0 +1,23 @@
+import { components } from '../schemas/openapi.js';
+import { RequestOptions, BaseClient, OpenMeterConfig } from './client.js';
+export type PortalToken = components['schemas']['PortalToken'];
+export declare class PortalClient extends BaseClient {
+    constructor(config: OpenMeterConfig);
+    /**
+     * Create portal token
+     * Useful for creating a token sharable with your customer to query their own usage
+     * @note OpenMeter Cloud only feature
+     */
+    createToken(token: {
+        subject: string;
+        expiresAt?: Date;
+        allowedMeterSlugs?: string[];
+    }, options?: RequestOptions): Promise<PortalToken>;
+    /**
+     * Invalidate portal token
+     * @note OpenMeter Cloud only feature
+     */
+    invalidateTokens(invalidate?: {
+        subject?: string;
+    }, options?: RequestOptions): Promise<void>;
+}

package/dist/clients/portal.js

@@ -0,0 +1,37 @@
+import { BaseClient } from './client.js';
+export class PortalClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Create portal token
+     * Useful for creating a token sharable with your customer to query their own usage
+     * @note OpenMeter Cloud only feature
+     */
+    async createToken(token, options) {
+        return await this.request({
+            path: '/api/v1/portal/tokens',
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(token),
+            options,
+        });
+    }
+    /**
+     * Invalidate portal token
+     * @note OpenMeter Cloud only feature
+     */
+    async invalidateTokens(invalidate = {}, options) {
+        return await this.request({
+            path: '/api/v1/portal/tokens/invalidate',
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(invalidate),
+            options,
+        });
+    }
+}

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 import { OpenMeterConfig } from './clients/client.js';
 import { EventsClient } from './clients/event.js';
 import { MetersClient } from './clients/meter.js';
+import { PortalClient } from './clients/portal.js';
 export { OpenMeterConfig, RequestOptions } from './clients/client.js';
-export { Event } from './clients/event.js';
-export { Meter, MeterValue, MeterAggregation, WindowSize } from './clients/meter.js';
+export { Event, IngestedEvent } from './clients/event.js';
+export { Meter, MeterAggregation, WindowSize } from './clients/meter.js';
+export { createOpenAIStreamCallback } from './next.js';
 export declare class OpenMeter {
     events: EventsClient;
     meters: MetersClient;
+    portal: PortalClient;
     constructor(config: OpenMeterConfig);
 }

package/dist/index.js

@@ -1,11 +1,15 @@
 import { EventsClient } from './clients/event.js';
 import { MetersClient } from './clients/meter.js';
+import { PortalClient } from './clients/portal.js';
 export { MeterAggregation, WindowSize } from './clients/meter.js';
+export { createOpenAIStreamCallback } from './next.js';
 export class OpenMeter {
     events;
     meters;
+    portal;
     constructor(config) {
         this.events = new EventsClient(config);
         this.meters = new MetersClient(config);
+        this.portal = new PortalClient(config);
     }
 }

package/dist/next.d.ts

@@ -0,0 +1,15 @@
+import type { OpenAIStreamCallbacks } from 'ai';
+import type { TiktokenModel } from 'js-tiktoken';
+type OpenAIUsage = {
+    total_tokens: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+};
+type OpenAIStreamCallbacksWithUsage = OpenAIStreamCallbacks & {
+    onUsage?: (usage: OpenAIUsage) => Promise<void> | void;
+};
+export declare function createOpenAIStreamCallback({ model, prompts, }: {
+    model: TiktokenModel;
+    prompts: string[];
+}, openAIStreamCallbacks: OpenAIStreamCallbacksWithUsage): Promise<OpenAIStreamCallbacks>;
+export {};

package/dist/next.js

@@ -0,0 +1,46 @@
+let encodingForModel;
+export async function createOpenAIStreamCallback({ model, prompts, }, openAIStreamCallbacks) {
+    // Tiktoken is an optional dependency, so we import it conditionally
+    if (!encodingForModel) {
+        const { encodingForModel: encodingForModel_ } = await import('js-tiktoken');
+        encodingForModel = encodingForModel_;
+    }
+    const enc = encodingForModel(model);
+    let promptTokens = 0;
+    let completionTokens = 0;
+    const streamCallbacks = {
+        ...openAIStreamCallbacks,
+        async onStart() {
+            for (const content of prompts) {
+                const tokens = enc.encode(content);
+                promptTokens += tokens.length;
+            }
+            if (typeof openAIStreamCallbacks?.onStart === 'function') {
+                return openAIStreamCallbacks.onStart();
+            }
+        },
+        async onToken(content) {
+            // To test tokenizaton see: https://platform.openai.com/tokenizer
+            const tokens = enc.encode(content);
+            completionTokens += tokens.length;
+            if (typeof openAIStreamCallbacks?.onToken === 'function') {
+                return openAIStreamCallbacks.onToken(content);
+            }
+        },
+        async onFinal(completion) {
+            // Mimicking OpenAI usage metadata API
+            const usage = {
+                total_tokens: promptTokens + completionTokens,
+                prompt_tokens: promptTokens,
+                completion_tokens: completionTokens,
+            };
+            if (typeof openAIStreamCallbacks?.onUsage === 'function') {
+                await openAIStreamCallbacks.onUsage(usage);
+            }
+            if (typeof openAIStreamCallbacks?.onFinal === 'function') {
+                return openAIStreamCallbacks.onFinal(completion);
+            }
+        },
+    };
+    return streamCallbacks;
+}