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

package/README.md

@@ -3,7 +3,7 @@
 ## Install
 
 ```sh
-npm install --save @openmeter/sdk@alpha
+npm install --save @openmeter/sdk@beta
 ```
 
 ## Example
@@ -15,78 +15,74 @@ 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)
 ```
 
 ### 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
+#### values
+
+Get back 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.values('my-meter-slug', {
+    subject: 'user-1',
+    from: new Date('2021-01-01'),
+    to: new Date('2021-01-02'),
+    windowSize: WindowSize.HOUR
+})
 ```

package/clients/client.ts

@@ -0,0 +1,153 @@
+import { IncomingHttpHeaders } from 'http'
+import { Dispatcher, request } 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']
+
+type UndiciRequestOptions = { dispatcher?: Dispatcher } & Omit<Dispatcher.RequestOptions, 'origin' | 'path' | 'method'> & Partial<Pick<Dispatcher.RequestOptions, 'method'>>
+
+export class BaseClient {
+    protected config: OpenMeterConfig
+
+    constructor(config: OpenMeterConfig) {
+        this.config = config
+    }
+
+    protected async 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> {
+        // Building URL
+        const url = this.getUrl(path, searchParams)
+
+        // Request options
+        const reqHeaders: IncomingHttpHeaders = {
+            Accept: 'application/json',
+            ...headers,
+            ...this.getAuthHeaders(),
+            ...this.config.headers,
+            ...options?.headers,
+        }
+        const reqOpts: UndiciRequestOptions = {
+            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() as Problem
+                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) {
+            return undefined as unknown as T
+        }
+        if (resp.headers['content-type'] === 'application/json') {
+            return await resp.body.json() as T
+        }
+        if (!resp.headers['content-type']) {
+            throw new Error('Missing content type')
+        }
+
+        throw new Error(`Unknown content type: ${resp.headers['content-type']}`)
+    }
+
+    protected getUrl(path: string, searchParams?: URLSearchParams) {
+        let qs = searchParams ? searchParams.toString() : ''
+        qs = qs.length > 0 ? `?${qs}` : ''
+        const url = new URL(`${path}${qs}`, this.config.baseUrl)
+        return url
+    }
+
+    protected getAuthHeaders(): IncomingHttpHeaders {
+        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 {}
+    }
+
+    protected static toURLSearchParams(params: Record<string, string | number | Date | string[]>): URLSearchParams {
+        const searchParams = new URLSearchParams()
+
+        for (const [key, value] of Object.entries(params)) {
+            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 {
+    public statusCode: number
+    public problem?: Problem
+
+    constructor({ statusCode, problem }: { statusCode: number; problem?: Problem }) {
+        super(problem?.type || 'unexpected status code')
+        this.name = 'HttpError'
+        this.statusCode = statusCode
+        this.problem = problem
+    }
+}

package/clients/event.ts

@@ -0,0 +1,109 @@
+import crypto from 'crypto'
+import { components } from '../schemas/openapi.js'
+import { RequestOptions, BaseClient, OpenMeterConfig } from './client.js'
+
+// We export Event instead
+type CloudEvents = components['schemas']['Event']
+
+/**
+ * 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 class EventsClient extends BaseClient {
+    constructor(config: OpenMeterConfig) {
+        super(config)
+    }
+
+    /**
+     * Ingest usage event in a CloudEvents format
+     * @see https://cloudevents.io
+     */
+    public async ingest(
+        usageEvent: Event,
+        options?: RequestOptions
+    ): Promise<void> {
+        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: CloudEvents = {
+            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
+        })
+    }
+}
+

package/clients/meter.ts

@@ -0,0 +1,84 @@
+import { paths, components } from '../schemas/openapi.js'
+import { BaseClient, OpenMeterConfig, RequestOptions } from './client.js'
+
+export enum WindowSize {
+    MINUTE = 'MINUTE',
+    HOUR = 'HOUR',
+    DAY = 'DAY'
+}
+
+export enum MeterAggregation {
+    SUM = 'SUM',
+    COUNT = 'COUNT',
+    AVG = 'AVG',
+    MIN = 'MIN',
+    MAX = 'MAX',
+}
+
+export type MeterQueryParams = {
+    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 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. */
+    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 Meter = components['schemas']['Meter']
+export type WindowSizeType = components['schemas']['WindowSize']
+
+export class MetersClient extends BaseClient {
+    constructor(config: OpenMeterConfig) {
+        super(config)
+    }
+
+    /**
+     * Get one meter by slug
+     */
+    public async get(slug: string, options?: RequestOptions): Promise<Meter> {
+        return this.request<Meter>({
+            method: 'GET',
+            path: `/api/v1/meters/${slug}`,
+            options,
+        })
+    }
+
+    /**
+     * List meters
+     */
+    public async list(options?: RequestOptions): Promise<Meter[]> {
+        return this.request<Meter[]>({
+            method: 'GET',
+            path: `/api/v1/meters`,
+            options,
+        })
+    }
+
+    /**
+     * Get aggregated values of a meter
+     */
+    public async values(slug: string, params?: MeterQueryParams, options?: RequestOptions): Promise<MeterQueryResponse> {
+        const searchParams = params ? BaseClient.toURLSearchParams(params) : undefined
+        return this.request<MeterQueryResponse>({
+            method: 'GET',
+            path: `/api/v1/meters/${slug}/values`,
+            searchParams,
+            options,
+        })
+    }
+}
+

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[]>): 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,101 @@
+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) {
+            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 (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,65 @@
+import { RequestOptions, BaseClient, OpenMeterConfig } from './client.js';
+/**
+ * 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>;
+}