@openmeter/sdk 1.0.0-alpha.4 → 1.0.0-beta.13

package/README.md

@@ -3,7 +3,7 @@
 ## Install
 
 ```sh
-npm install --save @openmeter/sdk@alpha
+npm install --save @openmeter/sdk
 ```
 
 ## Example
@@ -15,78 +15,146 @@ 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().toISOString(),
- 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.ingestEvents(event)
+await openmeter.events.ingest(event)
 
 // Fetching a meter
-const meter = await openmeter.meters.getMeter('m1')
+const meter = await openmeter.meters.get('m1')
 ```
 
 ## API
 
-The OpenMeter SDK uses [openapi-typescript-codegen](https://www.npmjs.com/package/openapi-typescript-codegen) under the hood to generate the HTTP client.
-
 ### Events
 
-#### ingestEvents
+#### ingest
 
 ```ts
 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().toISOString(),
- 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.ingestEvents(event)
+await openmeter.events.ingest(event)
+```
+
+#### list
+
+Retrieve latest raw events. Useful for debugging.
+
+```ts
+const events = await openmeter.events.list()
 ```
 
 ### Meters
 
-#### listMeters
+#### list
+
+List meters.
 
 ```ts
-const meters = await openmeter.meters.listMeters()
+const meters = await openmeter.meters.list()
 ```
 
-#### getMeter
+#### get
+
+Get one meter by slug.
 
 ```ts
-const meter = await openmeter.meters.getMeter('m1')
+const meter = await openmeter.meters.get('m1')
 ```
 
-#### getMeterValues
+#### query
+
+Query meter values.
 
 ```ts
-import { type WindowSize } from '@openmeter/sdk'
-
-const meterSlug = 'm2'
-const namespace = undefined
-const subject = 'user-1'
-const from = new Date('2021-01-01').toISOString()
-const to = new Date('2021-01-02').toISOString()
-const windowSize = WindowSize.HOUR
-const values = await openmeter.meters.getMeterValues(
- meterSlug,
- namespace,
- subject,
- from,
- to,
- windowSize
-)
+import { WindowSize } from '@openmeter/sdk'
+
+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')
+```
+
+## 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

@@ -0,0 +1,40 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import { IncomingHttpHeaders } from 'http';
+import { Dispatcher } from 'undici';
+import { components } from '../schemas/openapi.js';
+export type OpenMeterConfig = {
+    baseUrl: string;
+    token?: string;
+    username?: string;
+    password?: string;
+    headers?: IncomingHttpHeaders;
+};
+export type RequestOptions = {
+    headers?: IncomingHttpHeaders;
+};
+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, }: {
+        path: string;
+        method: Dispatcher.HttpMethod;
+        searchParams?: URLSearchParams;
+        headers?: IncomingHttpHeaders;
+        body?: string | Buffer | Uint8Array;
+        options?: RequestOptions;
+    }): Promise<T>;
+    protected getUrl(path: string, searchParams?: URLSearchParams): import("url").URL;
+    protected getAuthHeaders(): IncomingHttpHeaders;
+    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, }: {
+        statusCode: number;
+        problem?: Problem;
+    });
+}

package/dist/clients/client.js

@@ -0,0 +1,104 @@
+import { request } from 'undici';
+export class BaseClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request({ path, method, searchParams, headers, body, options, }) {
+        // Building URL
+        const url = this.getUrl(path, searchParams);
+        // Request options
+        const reqHeaders = {
+            Accept: 'application/json',
+            ...headers,
+            ...this.getAuthHeaders(),
+            ...this.config.headers,
+            ...options?.headers,
+        };
+        const reqOpts = {
+            method,
+            headers: reqHeaders,
+        };
+        // Optional body
+        if (body) {
+            if (!reqHeaders['Content-Type'] && !reqHeaders['content-type']) {
+                throw new Error('Content Type is required with body');
+            }
+            reqOpts.body = body;
+        }
+        const resp = await request(url, reqOpts);
+        // Error handling
+        if (resp.statusCode > 399) {
+            if (resp.headers['content-type'] === 'application/problem+json') {
+                const problem = (await resp.body.json());
+                throw new HttpError({
+                    statusCode: resp.statusCode,
+                    problem,
+                });
+            }
+            // Requests can fail before API, in this case we only have a status code
+            throw new HttpError({
+                statusCode: resp.statusCode,
+            });
+        }
+        // Response parsing
+        if (resp.statusCode === 204 || resp.headers['content-length'] === '0') {
+            return undefined;
+        }
+        if (resp.headers['content-type'] === 'application/json') {
+            return (await resp.body.json());
+        }
+        if (!resp.headers['content-type']) {
+            throw new Error('Missing content type');
+        }
+        throw new Error(`Unknown content type: ${resp.headers['content-type']}`);
+    }
+    getUrl(path, searchParams) {
+        let qs = searchParams ? searchParams.toString() : '';
+        qs = qs.length > 0 ? `?${qs}` : '';
+        const url = new URL(`${path}${qs}`, this.config.baseUrl);
+        return url;
+    }
+    getAuthHeaders() {
+        if (this.config.token) {
+            return {
+                authorization: `Bearer ${this.config.token}`,
+            };
+        }
+        if (this.config.username && this.config.password) {
+            const encoded = Buffer.from(`${this.config.username}:${this.config.password}`).toString('base64');
+            return {
+                authorization: `Basic ${encoded}`,
+            };
+        }
+        return {};
+    }
+    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(','));
+            }
+            else if (value instanceof Date) {
+                searchParams.append(key, value.toISOString());
+            }
+            else {
+                searchParams.append(key, value.toString());
+            }
+        }
+        return searchParams;
+    }
+}
+export class HttpError extends Error {
+    statusCode;
+    problem;
+    constructor({ statusCode, problem, }) {
+        super(problem?.type || 'unexpected status code');
+        this.name = 'HttpError';
+        this.statusCode = statusCode;
+        this.problem = problem;
+    }
+}

package/dist/clients/event.d.ts

@@ -0,0 +1,79 @@
+import { components } from '../schemas/openapi.js';
+import { RequestOptions, BaseClient, OpenMeterConfig } from './client.js';
+type CloudEvents = components['schemas']['Event'];
+export type EventsQueryParams = {
+    /**
+     * @description Limit number of results. Max: 100
+     * @example 25
+     */
+    limit?: number;
+};
+/**
+ * Usage Event
+ */
+export type Event = {
+    /**
+     * @description The version of the CloudEvents specification which the event uses.
+     * @example 1.0
+     */
+    specversion?: string;
+    /**
+     * @description Unique identifier for the event, defaults to uuid v4.
+     * @example "5c10fade-1c9e-4d6c-8275-c52c36731d3c"
+     */
+    id?: string;
+    /**
+     * Format: uri-reference
+     * @description Identifies the context in which an event happened, defaults to: @openmeter/sdk
+     * @example services/service-0
+     */
+    source?: string;
+    /**
+     * @description Describes the type of event related to the originating occurrence.
+     * @example "api_request"
+     */
+    type: string;
+    /**
+     * @description Describes the subject of the event in the context of the event producer (identified by source).
+     * @example "customer_id"
+     */
+    subject: string;
+    /**
+     * Format: date-time
+     * @description Date of when the occurrence happened.
+     * @example new Date('2023-01-01T01:01:01.001Z')
+     */
+    time?: Date;
+    /**
+     * Format: uri
+     * @description Identifies the schema that data adheres to.
+     */
+    dataschema?: string;
+    /**
+     * @description Content type of the data value. Must adhere to RFC 2046 format.
+     * @example application/json
+     * @enum {string|null}
+     */
+    datacontenttype?: 'application/json';
+    /**
+     * @description The event payload.
+     * @example {
+     *   "duration_ms": "12",
+     *   "path": "/hello"
+     * }
+     */
+    data: Record<string, string | number | Record<string, string | number>>;
+};
+export declare class EventsClient extends BaseClient {
+    constructor(config: OpenMeterConfig);
+    /**
+     * Ingest usage event in a CloudEvents format
+     * @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

@@ -0,0 +1,53 @@
+import crypto from 'crypto';
+import { BaseClient } from './client.js';
+export class EventsClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Ingest usage event in a CloudEvents format
+     * @see https://cloudevents.io
+     */
+    async ingest(usageEvent, options) {
+        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
+        const body = {
+            specversion: usageEvent.specversion ?? '1.0',
+            id: usageEvent.id ?? crypto.randomUUID(),
+            source: usageEvent.source ?? '@openmeter/sdk',
+            type: usageEvent.type,
+            subject: usageEvent.subject,
+            time: usageEvent.time?.toISOString(),
+            datacontenttype: usageEvent.datacontenttype,
+            dataschema: usageEvent.dataschema,
+            data: usageEvent.data,
+        };
+        // Making Request
+        return await this.request({
+            path: '/api/v1/events',
+            method: 'POST',
+            body: JSON.stringify(body),
+            headers: {
+                'Content-Type': 'application/cloudevents+json',
+            },
+            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

@@ -0,0 +1,96 @@
+import { paths, components } from '../schemas/openapi.js';
+import { BaseClient, OpenMeterConfig, RequestOptions } from './client.js';
+export declare enum WindowSize {
+    MINUTE = "MINUTE",
+    HOUR = "HOUR",
+    DAY = "DAY"
+}
+export declare enum MeterAggregation {
+    SUM = "SUM",
+    COUNT = "COUNT",
+    AVG = "AVG",
+    MIN = "MIN",
+    MAX = "MAX"
+}
+export type MeterValuesParams = {
+    /**
+     * @description Subject(s) to filter by.
+     * @example ["customer-1", "customer-2"]
+     */
+    subject?: string;
+    /**
+     * @description Start date.
+     * Must be aligned with the window size.
+     * Inclusive.
+     */
+    from?: Date;
+    /**
+     * @description End date.
+     * Must be aligned with the window size.
+     * Inclusive.
+     */
+    to?: Date;
+    /**
+     * @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 Group By
+     * If not specified a single aggregate will be returned for each subject and time window.
+     */
+    groupBy?: string[];
+};
+export type MeterQueryParams = {
+    /**
+     * @description Subject(s) to filter by.
+     * @example ["customer-1", "customer-2"]
+     */
+    subject?: string[];
+    /**
+     * @description Start date.
+     * Must be aligned with the window size.
+     * Inclusive.
+     */
+    from?: Date;
+    /**
+     * @description End date.
+     * Must be aligned with the window size.
+     * Inclusive.
+     */
+    to?: Date;
+    /**
+     * @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 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}/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 {
+    constructor(config: OpenMeterConfig);
+    /**
+     * Get one meter by slug
+     */
+    get(slug: string, options?: RequestOptions): Promise<Meter>;
+    /**
+     * List meters
+     */
+    list(options?: RequestOptions): Promise<Meter[]>;
+    /**
+     * Query a meter
+     */
+    query(slug: string, params?: MeterQueryParams, options?: RequestOptions): Promise<MeterQueryResponse>;
+    /**
+     * List subjects of a meter
+     */
+    subjects(slug: string, options?: RequestOptions): Promise<string[]>;
+}

package/dist/clients/meter.js

@@ -0,0 +1,64 @@
+import { BaseClient } from './client.js';
+export var WindowSize;
+(function (WindowSize) {
+    WindowSize["MINUTE"] = "MINUTE";
+    WindowSize["HOUR"] = "HOUR";
+    WindowSize["DAY"] = "DAY";
+})(WindowSize || (WindowSize = {}));
+export var MeterAggregation;
+(function (MeterAggregation) {
+    MeterAggregation["SUM"] = "SUM";
+    MeterAggregation["COUNT"] = "COUNT";
+    MeterAggregation["AVG"] = "AVG";
+    MeterAggregation["MIN"] = "MIN";
+    MeterAggregation["MAX"] = "MAX";
+})(MeterAggregation || (MeterAggregation = {}));
+export class MetersClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Get one meter by slug
+     */
+    async get(slug, options) {
+        return this.request({
+            method: 'GET',
+            path: `/api/v1/meters/${slug}`,
+            options,
+        });
+    }
+    /**
+     * List meters
+     */
+    async list(options) {
+        return this.request({
+            method: 'GET',
+            path: `/api/v1/meters`,
+            options,
+        });
+    }
+    /**
+     * Query a meter
+     */
+    async query(slug, params, options) {
+        const searchParams = params
+            ? BaseClient.toURLSearchParams(params)
+            : undefined;
+        return this.request({
+            method: 'GET',
+            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/index.d.ts

@@ -1,23 +1,12 @@
-export { NodeHttpRequest } from './generated/core/NodeHttpRequest.js';
-import { type OpenAPIConfig } from './generated/core/OpenAPI.js';
-import { HttpService } from './generated/HttpService.js';
-import { DefaultService, EventsService, MetersService } from './generated/index.js';
-import type { BaseHttpRequest } from './generated/core/BaseHttpRequest.js';
-export * from './generated/index.js';
-export type HttpRequestConstructor = new (config: OpenAPIConfig) => BaseHttpRequest;
-export type ClientConfig = {
-    baseUrl: string;
-    credentials?: OpenAPIConfig['CREDENTIALS'];
-    withCredentials?: OpenAPIConfig['WITH_CREDENTIALS'];
-    token?: OpenAPIConfig['TOKEN'];
-    username?: OpenAPIConfig['USERNAME'];
-    password?: OpenAPIConfig['PASSWORD'];
-    headers?: OpenAPIConfig['HEADERS'];
-};
-export declare class OpenMeter extends HttpService {
-    readonly request: BaseHttpRequest;
-    readonly default: DefaultService;
-    readonly events: EventsService;
-    readonly meters: MetersService;
-    constructor(config: ClientConfig, HttpRequest?: HttpRequestConstructor);
+import { OpenMeterConfig } from './clients/client.js';
+import { EventsClient } from './clients/event.js';
+import { MetersClient } from './clients/meter.js';
+export { OpenMeterConfig, RequestOptions } from './clients/client.js';
+export { Event } 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;
+    constructor(config: OpenMeterConfig);
 }