@metronome/sdk 0.1.0-alpha.0

package/src/resources/usage.ts

@@ -0,0 +1,245 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import * as Core from "../core";
+import { APIResource } from "../resource";
+import * as UsageAPI from "./usage";
+
+export class Usage extends APIResource {
+  /**
+   * Fetch aggregated usage data for multiple customers and billable-metrics, broken
+   * into intervals of the specified length.
+   */
+  list(params: UsageListParams, options?: Core.RequestOptions): Core.APIPromise<UsageListResponse> {
+    const { next_page, ...body } = params;
+    return this._client.post('/usage', { query: { next_page }, body, ...options });
+  }
+
+  /**
+   * Send usage events to Metronome. The body of this request is expected to be a
+   * JSON array of between 1 and 100 usage events. Compressed request bodies are
+   * supported with a `Content-Encoding: gzip` header. See
+   * [Getting usage into Metronome](https://docs.metronome.com/getting-usage-data-into-metronome/overview)
+   * to learn more about usage events.
+   */
+  ingest(body: UsageIngestParams, options?: Core.RequestOptions): Core.APIPromise<void> {
+    return this._client.post('/ingest', {
+      body,
+      ...options,
+      headers: { Accept: '*/*', ...options?.headers },
+    });
+  }
+
+  /**
+   * Fetch aggregated usage data for the specified customer, billable-metric, and
+   * optional group, broken into intervals of the specified length.
+   */
+  listWithGroups(
+    params: UsageListWithGroupsParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<UsageListWithGroupsResponse> {
+    const { limit, next_page, ...body } = params;
+    return this._client.post('/usage/groups', { query: { limit, next_page }, body, ...options });
+  }
+}
+
+export interface UsageListResponse {
+  data: Array<UsageListResponse.Data>;
+
+  next_page: string | null;
+}
+
+export namespace UsageListResponse {
+  export interface Data {
+    billable_metric_id: string;
+
+    billable_metric_name: string;
+
+    customer_id: string;
+
+    end_timestamp: string;
+
+    start_timestamp: string;
+
+    value: number | null;
+
+    /**
+     * Values will be either a number or null. Null indicates that there were no
+     * matches for the group_by value.
+     */
+    groups?: Record<string, number | null>;
+  }
+}
+
+export interface UsageListWithGroupsResponse {
+  data: Array<UsageListWithGroupsResponse.Data>;
+
+  next_page: string | null;
+}
+
+export namespace UsageListWithGroupsResponse {
+  export interface Data {
+    ending_before: string;
+
+    group_key: string | null;
+
+    group_value: string | null;
+
+    starting_on: string;
+
+    value: number | null;
+  }
+}
+
+export interface UsageListParams {
+  /**
+   * Body param:
+   */
+  ending_before: string;
+
+  /**
+   * Body param:
+   */
+  starting_on: string;
+
+  /**
+   * Body param: A window_size of "day" or "hour" will return the usage for the
+   * specified period segmented into daily or hourly aggregates. A window_size of
+   * "none" will return a single usage aggregate for the entirety of the specified
+   * period.
+   */
+  window_size: 'hour' | 'day' | 'none' | 'HOUR' | 'DAY' | 'NONE' | 'Hour' | 'Day' | 'None';
+
+  /**
+   * Query param: Cursor that indicates where the next page of results should start.
+   */
+  next_page?: string;
+
+  /**
+   * Body param: A list of billable metrics to fetch usage for. If absent, all
+   * billable metrics will be returned.
+   */
+  billable_metrics?: Array<UsageListParams.BillableMetric>;
+
+  /**
+   * Body param: A list of Metronome customer IDs to fetch usage for. If absent,
+   * usage for all customers will be returned.
+   */
+  customer_ids?: Array<string>;
+}
+
+export namespace UsageListParams {
+  export interface BillableMetric {
+    id: string;
+
+    group_by?: BillableMetric.GroupBy;
+  }
+
+  export namespace BillableMetric {
+    export interface GroupBy {
+      /**
+       * The name of the group_by key to use
+       */
+      key: string;
+
+      /**
+       * Values of the group_by key to return in the query. If this field is omitted, all
+       * available values will be returned, up to a maximum of 200.
+       */
+      values?: Array<string>;
+    }
+  }
+}
+
+export type UsageIngestParams = Array<UsageIngestParams.Usage>;
+
+export namespace UsageIngestParams {
+  export interface Usage {
+    customer_id: string;
+
+    event_type: string;
+
+    /**
+     * RFC 3339 formatted
+     */
+    timestamp: string;
+
+    transaction_id: string;
+
+    properties?: Record<string, unknown>;
+  }
+}
+
+export interface UsageListWithGroupsParams {
+  /**
+   * Body param:
+   */
+  billable_metric_id: string;
+
+  /**
+   * Body param:
+   */
+  customer_id: string;
+
+  /**
+   * Body param: A window_size of "day" or "hour" will return the usage for the
+   * specified period segmented into daily or hourly aggregates. A window_size of
+   * "none" will return a single usage aggregate for the entirety of the specified
+   * period.
+   */
+  window_size: 'hour' | 'day' | 'none' | 'HOUR' | 'DAY' | 'NONE' | 'Hour' | 'Day' | 'None';
+
+  /**
+   * Query param: Max number of results that should be returned
+   */
+  limit?: number;
+
+  /**
+   * Query param: Cursor that indicates where the next page of results should start.
+   */
+  next_page?: string;
+
+  /**
+   * Body param: If true, will return the usage for the current billing period. Will
+   * return an error if the customer is currently uncontracted or starting_on and
+   * ending_before are specified when this is true.
+   */
+  current_period?: boolean;
+
+  /**
+   * Body param:
+   */
+  ending_before?: string;
+
+  /**
+   * Body param:
+   */
+  group_by?: UsageListWithGroupsParams.GroupBy;
+
+  /**
+   * Body param:
+   */
+  starting_on?: string;
+}
+
+export namespace UsageListWithGroupsParams {
+  export interface GroupBy {
+    /**
+     * The name of the group_by key to use
+     */
+    key: string;
+
+    /**
+     * Values of the group_by key to return in the query. Omit this if you'd like all
+     * values for the key returned.
+     */
+    values?: Array<string>;
+  }
+}
+
+export namespace Usage {
+  export import UsageListResponse = UsageAPI.UsageListResponse;
+  export import UsageListWithGroupsResponse = UsageAPI.UsageListWithGroupsResponse;
+  export import UsageListParams = UsageAPI.UsageListParams;
+  export import UsageIngestParams = UsageAPI.UsageIngestParams;
+  export import UsageListWithGroupsParams = UsageAPI.UsageListWithGroupsParams;
+}

package/src/resources/webhooks.ts

@@ -0,0 +1,120 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../resource';
+import { createHmac } from 'crypto';
+import { getRequiredHeader, HeadersLike } from '../core';
+
+export class Webhooks extends APIResource {
+  /**
+   * Validates that the given payload was sent by Metronome and parses the payload.
+   */
+  unwrap(
+    payload: string,
+    headers: HeadersLike,
+    secret: string | undefined | null = this._client.webhookSecret,
+  ): Object {
+    this.verifySignature(payload, headers, secret);
+    return JSON.parse(payload);
+  }
+
+  private validateSecret(secret: string | null | undefined): asserts secret is string {
+    if (typeof secret !== 'string') {
+      throw new Error(
+        "The webhook secret must either be set using the env var, METRONOME_WEBHOOK_SECRET, on the client class, Metronome({ webhook_secret: '123' }), or passed to this function",
+      );
+    }
+
+    return;
+  }
+
+  private signPayload(payload: string, { date, secret }: { date: string; secret: string }) {
+    const encoder = new TextEncoder();
+    const toSign = encoder.encode(`${date}\n${payload}`);
+
+    const hmac = createHmac('sha256', secret);
+    hmac.update(toSign);
+
+    return hmac.digest('hex');
+  }
+
+  /** Make an assertion, if not `true`, then throw. */
+  private assert(expr: unknown, msg = ''): asserts expr {
+    if (!expr) {
+      throw new Error(msg);
+    }
+  }
+
+  /** Compare to array buffers or data views in a way that timing based attacks
+   * cannot gain information about the platform. */
+  private timingSafeEqual(
+    a: ArrayBufferView | ArrayBufferLike | DataView,
+    b: ArrayBufferView | ArrayBufferLike | DataView,
+  ): boolean {
+    if (a.byteLength !== b.byteLength) {
+      return false;
+    }
+    if (!(a instanceof DataView)) {
+      a = new DataView(ArrayBuffer.isView(a) ? a.buffer : a);
+    }
+    if (!(b instanceof DataView)) {
+      b = new DataView(ArrayBuffer.isView(b) ? b.buffer : b);
+    }
+    this.assert(a instanceof DataView);
+    this.assert(b instanceof DataView);
+    const length = a.byteLength;
+    let out = 0;
+    let i = -1;
+    while (++i < length) {
+      out |= a.getUint8(i) ^ b.getUint8(i);
+    }
+    return out === 0;
+  }
+
+  /**
+   * Validates whether or not the webhook payload was sent by Metronome.
+   *
+   * An error will be raised if the webhook payload was not sent by Metronome.
+   */
+  verifySignature(
+    body: string,
+    headers: HeadersLike,
+    secret: string | undefined | null = this._client.webhookSecret,
+  ): void {
+    this.validateSecret(secret);
+
+    const msgDate = getRequiredHeader(headers, 'Date');
+    const msgSignature = getRequiredHeader(headers, 'Metronome-Webhook-Signature');
+
+    const now = Date.now();
+    const timestampSeconds = Math.floor(new Date(msgDate).valueOf());
+
+    if (isNaN(timestampSeconds)) {
+      throw new Error(`Invalid timestamp header: ${msgDate}`);
+    }
+
+    if (typeof body !== 'string') {
+      throw new Error(
+        'Webhook body must be passed as the raw JSON string sent from the server (do not parse it first).',
+      );
+    }
+
+    const webhook_tolerance_in_seconds = 5 * 60; // 5 minutes
+    if (now - timestampSeconds > webhook_tolerance_in_seconds) {
+      throw new Error('Webhook timestamp is too old');
+    }
+
+    if (timestampSeconds > now + webhook_tolerance_in_seconds) {
+      throw new Error('Webhook timestamp is too new');
+    }
+
+    const expectedSignature = this.signPayload(body, { date: msgDate, secret });
+    const encoder = new globalThis.TextEncoder();
+
+    if (this.timingSafeEqual(encoder.encode(msgSignature), encoder.encode(expectedSignature))) {
+      // valid!
+      return;
+    }
+
+    throw new Error('The given webhook signature does not match the expected signature');
+  }
+}

package/src/shims/node.ts

@@ -0,0 +1,50 @@
+// @ts-ignore
+import * as types from '../_shims/node-types';
+import { setShims } from '../_shims/registry';
+import { getRuntime } from '../_shims/node-runtime';
+setShims(getRuntime());
+
+declare module '../_shims/manual-types' {
+  export namespace manual {
+    // @ts-ignore
+    export type Agent = types.Agent;
+    // @ts-ignore
+    export import fetch = types.fetch;
+    // @ts-ignore
+    export type Request = types.Request;
+    // @ts-ignore
+    export type RequestInfo = types.RequestInfo;
+    // @ts-ignore
+    export type RequestInit = types.RequestInit;
+    // @ts-ignore
+    export type Response = types.Response;
+    // @ts-ignore
+    export type ResponseInit = types.ResponseInit;
+    // @ts-ignore
+    export type ResponseType = types.ResponseType;
+    // @ts-ignore
+    export type BodyInit = types.BodyInit;
+    // @ts-ignore
+    export type Headers = types.Headers;
+    // @ts-ignore
+    export type HeadersInit = types.HeadersInit;
+    // @ts-ignore
+    export type BlobPropertyBag = types.BlobPropertyBag;
+    // @ts-ignore
+    export type FilePropertyBag = types.FilePropertyBag;
+    // @ts-ignore
+    export type FileFromPathOptions = types.FileFromPathOptions;
+    // @ts-ignore
+    export import FormData = types.FormData;
+    // @ts-ignore
+    export import File = types.File;
+    // @ts-ignore
+    export import Blob = types.Blob;
+    // @ts-ignore
+    export type Readable = types.Readable;
+    // @ts-ignore
+    export type FsReadStream = types.FsReadStream;
+    // @ts-ignore
+    export import ReadableStream = types.ReadableStream;
+  }
+}

package/src/shims/web.ts

@@ -0,0 +1,50 @@
+// @ts-ignore
+import * as types from '../_shims/web-types';
+import { setShims } from '../_shims/registry';
+import { getRuntime } from '../_shims/web-runtime';
+setShims(getRuntime({ manuallyImported: true }));
+
+declare module '../_shims/manual-types' {
+  export namespace manual {
+    // @ts-ignore
+    export type Agent = types.Agent;
+    // @ts-ignore
+    export import fetch = types.fetch;
+    // @ts-ignore
+    export type Request = types.Request;
+    // @ts-ignore
+    export type RequestInfo = types.RequestInfo;
+    // @ts-ignore
+    export type RequestInit = types.RequestInit;
+    // @ts-ignore
+    export type Response = types.Response;
+    // @ts-ignore
+    export type ResponseInit = types.ResponseInit;
+    // @ts-ignore
+    export type ResponseType = types.ResponseType;
+    // @ts-ignore
+    export type BodyInit = types.BodyInit;
+    // @ts-ignore
+    export type Headers = types.Headers;
+    // @ts-ignore
+    export type HeadersInit = types.HeadersInit;
+    // @ts-ignore
+    export type BlobPropertyBag = types.BlobPropertyBag;
+    // @ts-ignore
+    export type FilePropertyBag = types.FilePropertyBag;
+    // @ts-ignore
+    export type FileFromPathOptions = types.FileFromPathOptions;
+    // @ts-ignore
+    export import FormData = types.FormData;
+    // @ts-ignore
+    export import File = types.File;
+    // @ts-ignore
+    export import Blob = types.Blob;
+    // @ts-ignore
+    export type Readable = types.Readable;
+    // @ts-ignore
+    export type FsReadStream = types.FsReadStream;
+    // @ts-ignore
+    export import ReadableStream = types.ReadableStream;
+  }
+}

package/src/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  // this config is included in the published src directory to prevent TS errors
+  // from appearing when users go to source, and VSCode opens the source .ts file
+  // via declaration maps
+  "include": ["index.ts"],
+  "compilerOptions": {
+    "target": "es2015",
+    "lib": ["DOM"],
+    "moduleResolution": "node"
+  }
+}