@origincloud/billing 0.0.0-stage → 0.13.0

package/src/v1beta1/cost.ts

@@ -0,0 +1,296 @@
+// Code generated by the SDK's generator (generator/). DO NOT EDIT.
+// source: origincloud/billing/v1beta1/cost.proto
+
+import { type CallOptions, type Client, type Service, pathValue, query } from "@origincloud/core";
+
+/**
+ * Calls CostService.
+ *
+ * Usage and cost: what a project, an organization or a billing account used
+ * in a period, and what it costs, as read-only reports.
+ *
+ * Usage is metered per resource and priced when it is recorded, at the
+ * price list's rate then, so a later price change never changes a past
+ * cost. A running resource's usage is recorded at least hourly; the last
+ * hour can still be missing from a report.
+ */
+export class CostClient {
+  /**
+   * The endpoint the client sends its calls to, which also serves the
+   * operations its methods answer with.
+   */
+  readonly service: Service;
+
+  /** A client of CostService that sends its calls through `client`. */
+  constructor(client: Client) {
+    this.service = client.service("billing", false);
+  }
+
+  /**
+   * Returns a project's cost in a period, by service and product, in hourly
+   * or daily buckets. Needs `admin.usage.list` on the organization.
+   */
+  async queryProjectCost(request: QueryProjectCostRequest, options?: CallOptions): Promise<CostReport> {
+    const p0 = pathValue("project", request.project, "projects/*");
+    return this.service.call<CostReport>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}:queryCost`,
+        query: query(request, ["project"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Returns an organization's cost in a period: every project's together,
+   * by service and product, and each project's on its own. Needs
+   * `admin.usage.list` on the organization, which reads every project's
+   * cost in it.
+   */
+  async queryOrganizationCost(request: QueryOrganizationCostRequest, options?: CallOptions): Promise<OrganizationCostReport> {
+    const p0 = pathValue("organization", request.organization, "organizations/*");
+    return this.service.call<OrganizationCostReport>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}:queryCost`,
+        query: query(request, ["organization"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Returns what was charged to a billing account in a period, by service
+   * and product. A project's cost is charged to the account it was linked
+   * to when the usage was recorded, so moving a project moves only its
+   * later cost. Its spend limit compares the calendar month's total with
+   * `limit`. Needs `admin.spend_limit.get` on the organization.
+   */
+  async queryBillingAccountCost(request: QueryBillingAccountCostRequest, options?: CallOptions): Promise<CostReport> {
+    const p0 = pathValue("billingAccount", request.billingAccount, "organizations/*/billingAccounts/*");
+    return this.service.call<CostReport>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}:queryCost`,
+        query: query(request, ["billingAccount"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Lists a project's metered usage records that overlap a period, the
+   * input its cost is priced from, oldest first. Needs `admin.usage.list`
+   * on the organization.
+   */
+  async queryProjectUsage(request: QueryProjectUsageRequest, options?: CallOptions): Promise<QueryProjectUsageResponse> {
+    const p0 = pathValue("project", request.project, "projects/*");
+    return this.service.call<QueryProjectUsageResponse>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}:queryUsage`,
+        query: query(request, ["project"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Iterates over everything queryProjectUsage lists from the request's page on,
+   * fetching the next page as the loop reaches it. A page that fails ends
+   * the iteration with its error.
+   */
+  async *allUsageRecords(request: QueryProjectUsageRequest, options?: CallOptions): AsyncGenerator<UsageRecord, void, undefined> {
+    for (let page = request; ; ) {
+      const response = await this.queryProjectUsage(page, options);
+      yield* response.usageRecords ?? [];
+      if (!response.nextPageToken) return;
+      page = { ...page, pageToken: response.nextPageToken };
+    }
+  }
+}
+
+/** How finely a report's cost is bucketed. */
+export const Granularity = {
+  /** Not set: daily. */
+  GRANULARITY_UNSPECIFIED: "GRANULARITY_UNSPECIFIED",
+  /** One bucket per hour, starting on the hour. */
+  HOURLY: "HOURLY",
+  /** One bucket per day, starting at midnight UTC. */
+  DAILY: "DAILY",
+} as const;
+
+/** How finely a report's cost is bucketed. */
+export type Granularity = (typeof Granularity)[keyof typeof Granularity];
+
+/**
+ * A cost report: the period's total, by service and, within a service, by
+ * product. Every amount is in EUR, before VAT, as a decimal string.
+ */
+export interface CostReport {
+  /** The period's total. */
+  total?: string;
+  /**
+   * Each service with any cost in the period, such as `compute`, in name
+   * order.
+   */
+  services?: ServiceCost[];
+}
+
+/** One service's cost in a report. */
+export interface ServiceCost {
+  /**
+   * The service, the first segment of its products' keys, such as
+   * `compute`.
+   */
+  service?: string;
+  /** The service's total. */
+  total?: string;
+  /**
+   * Each of the service's products with any cost in the period, in key
+   * order.
+   */
+  products?: ProductCost[];
+}
+
+/** One product's cost in a report. */
+export interface ProductCost {
+  /** The product as the price list names it, such as `compute.gp1.core.2`. */
+  productKey?: string;
+  /** The product's total. */
+  total?: string;
+  /** The buckets with any cost, oldest first. */
+  buckets?: CostBucket[];
+}
+
+/** The cost of one hour or one day. */
+export interface CostBucket {
+  /** When the bucket starts. */
+  startTime?: string;
+  /** The bucket's cost. */
+  amount?: string;
+}
+
+/**
+ * An organization's cost report: its projects' together, and each
+ * project's.
+ */
+export interface OrganizationCostReport {
+  /** The period's total of every project. */
+  total?: string;
+  /** Each service with any cost in the period, over every project. */
+  services?: ServiceCost[];
+  /**
+   * Each project with any cost in the period, in id order, a project
+   * deleted since included.
+   */
+  projects?: ProjectCost[];
+}
+
+/** One project's cost in an organization's report, over every service. */
+export interface ProjectCost {
+  /** The project, `projects/{project}`. */
+  project?: string;
+  /** The project's total. */
+  total?: string;
+  /** The buckets with any cost, oldest first. */
+  buckets?: CostBucket[];
+}
+
+/**
+ * One metered interval of one resource: how much of a metric it used from
+ * `startTime` to `endTime`.
+ */
+export interface UsageRecord {
+  /** The kind of resource, such as `compute.instance`. */
+  resourceKind?: string;
+  /** The resource's id. */
+  resourceId?: string;
+  /** What was measured, such as `running_seconds`. */
+  metric?: string;
+  /**
+   * The product the usage is priced as, such as `compute.gp1.core.2`;
+   * empty for a kind of resource that has none.
+   */
+  productKey?: string;
+  /** How much was used, in the metric's unit, as a decimal string. */
+  quantity?: string;
+  /** When the interval starts. */
+  startTime?: string;
+  /** When the interval ends. */
+  endTime?: string;
+  /**
+   * The billing account the usage was charged to, the one the project was
+   * linked to when it was recorded; empty if it had none.
+   */
+  billingAccount?: string;
+}
+
+/** The request for QueryProjectCost. */
+export interface QueryProjectCostRequest {
+  /** The project, `projects/{project}`. */
+  project?: string;
+  /** The period's start, included. */
+  startTime?: string;
+  /** The period's end, left out; after `startTime`. */
+  endTime?: string;
+  /** How finely to bucket the cost; daily when unset. */
+  granularity?: Granularity;
+}
+
+/** The request for QueryOrganizationCost. */
+export interface QueryOrganizationCostRequest {
+  /** The organization, `organizations/{organization}`. */
+  organization?: string;
+  /** The period's start, included. */
+  startTime?: string;
+  /** The period's end, left out; after `startTime`. */
+  endTime?: string;
+  /** How finely to bucket the cost; daily when unset. */
+  granularity?: Granularity;
+}
+
+/** The request for QueryBillingAccountCost. */
+export interface QueryBillingAccountCostRequest {
+  /** The billing account. */
+  billingAccount?: string;
+  /** The period's start, included. */
+  startTime?: string;
+  /** The period's end, left out; after `startTime`. */
+  endTime?: string;
+  /** How finely to bucket the cost; daily when unset. */
+  granularity?: Granularity;
+}
+
+/** The request for QueryProjectUsage. */
+export interface QueryProjectUsageRequest {
+  /** The project, `projects/{project}`. */
+  project?: string;
+  /** The period's start: records that end after it are listed. */
+  startTime?: string;
+  /**
+   * The period's end: records that start before it are listed; after
+   * `startTime`.
+   */
+  endTime?: string;
+  /**
+   * The most records to return; the server clamps it, and 0 means its
+   * default.
+   */
+  pageSize?: number;
+  /** A previous response's `nextPageToken`, for the page after it. */
+  pageToken?: string;
+}
+
+/** The response for QueryProjectUsage. */
+export interface QueryProjectUsageResponse {
+  /** The usage records on this page. */
+  usageRecords?: UsageRecord[];
+  /** The token for the next page; empty on the last one. */
+  nextPageToken?: string;
+}

package/src/v1beta1/index.ts

@@ -0,0 +1,6 @@
+// Code generated by the SDK's generator (generator/). DO NOT EDIT.
+
+export * from "./billing_account.js";
+export * from "./cost.js";
+export * from "./price_list.js";
+export * from "./spend_limit.js";

package/src/v1beta1/price_list.ts

@@ -0,0 +1,113 @@
+// Code generated by the SDK's generator (generator/). DO NOT EDIT.
+// source: origincloud/billing/v1beta1/price_list.proto
+
+import { type CallOptions, type Client, type Service, query } from "@origincloud/core";
+
+/**
+ * Calls PriceListService.
+ *
+ * The public price list: the list price of every billable product, for
+ * anyone to read, websites included. It needs no access token.
+ *
+ * Unlike the rest of this API, its path has been `/v1/pricing` since before
+ * the API was published, and its fields are written in snake case, as
+ * websites read them.
+ */
+export class PriceListClient {
+  /**
+   * The endpoint the client sends its calls to, which also serves the
+   * operations its methods answer with.
+   */
+  readonly service: Service;
+
+  /** A client of PriceListService that sends its calls through `client`. */
+  constructor(client: Client) {
+    this.service = client.service("billing", false);
+  }
+
+  /**
+   * Returns the prices in effect now. The answer carries an `ETag`; a
+   * request that sends it back in `If-None-Match` is answered
+   * `304 Not Modified`, without a body, while the list is unchanged.
+   */
+  async getPriceList(request: GetPriceListRequest, options?: CallOptions): Promise<PriceList> {
+    return this.service.call<PriceList>(
+      {
+        method: "GET",
+        path: `/v1/pricing`,
+        query: query(request, []),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * The price list. Every amount is in EUR, before VAT, which depends on the
+ * customer's country and is added on the invoice.
+ */
+export interface PriceList {
+  /** Always `EUR`. */
+  currency?: string;
+  /** Always true: every amount is net, before VAT. */
+  amounts_exclude_vat?: boolean;
+  /**
+   * When a list price was last set, changed, took effect or ended: what a
+   * "prices last updated" line shows. Unset only while nothing is priced.
+   */
+  last_changed?: string;
+  /**
+   * One entry per product family with a price in effect, in the platform's
+   * catalog order: `compute_instance`, `network_floating_ip`,
+   * `network_nat_gateway`, `network_vpc_egress`, `network_vpc_ingress`,
+   * `network_vpc_internal`, `storage_volume`, `storage_snapshot`,
+   * `observability_custom_metric`, `observability_api_request`,
+   * `observability_ingested_sample`.
+   */
+  families?: PriceFamily[];
+}
+
+/** One product family's prices. */
+export interface PriceFamily {
+  /** The family, such as `compute_instance`. */
+  family?: string;
+  /**
+   * The family's prices in effect, by product key, numbers compared as
+   * numbers: a class's instance types run from smallest to largest.
+   */
+  prices?: Price[];
+}
+
+/** The list price of one product. */
+export interface Price {
+  /**
+   * The product the price bills, as usage and cost reports name it, such
+   * as `compute.gp1.core.2`, `storage.gp1` or `network.vpc_egress`.
+   */
+  product_key?: string;
+  /**
+   * The parts of the product key, split out: `instanceType` for an instance,
+   * `storageClass` for a volume. Empty for a product that has none.
+   */
+  dimensions?: Record<string, string>;
+  /**
+   * What is counted: `seconds`, `gib_hours`, `gb` (decimal, 10^9 bytes),
+   * `metric_months`, `requests` or `samples`.
+   */
+  unit_type?: string;
+  /**
+   * How many of the unit the amount pays for: `3600` seconds is an
+   * hourly rate, `1000` requests a rate per thousand.
+   */
+  unit_count?: number;
+  /** The price of that many units, as a decimal string. */
+  amount?: string;
+  /** When the price took effect. */
+  valid_from?: string;
+  /** When the price is to end; unset while no end is scheduled. */
+  valid_until?: string;
+}
+
+/** The request for GetPriceList, which takes nothing. */
+export interface GetPriceListRequest {}

package/src/v1beta1/spend_limit.ts

@@ -0,0 +1,111 @@
+// Code generated by the SDK's generator (generator/). DO NOT EDIT.
+// source: origincloud/billing/v1beta1/spend_limit.proto
+
+import { type CallOptions, type Client, type Service, pathValue, query } from "@origincloud/core";
+
+/**
+ * Calls SpendLimitService.
+ *
+ * Spend limits: an amount per calendar month for a billing account, and the
+ * shares of it at which an alert is emailed. A spend limit only alerts: it
+ * never stops or refuses anything.
+ *
+ * Access to spend limits is granted apart from access to billing accounts:
+ * an organization's owner holds it by default.
+ */
+export class SpendLimitClient {
+  /**
+   * The endpoint the client sends its calls to, which also serves the
+   * operations its methods answer with.
+   */
+  readonly service: Service;
+
+  /** A client of SpendLimitService that sends its calls through `client`. */
+  constructor(client: Client) {
+    this.service = client.service("billing", false);
+  }
+
+  /**
+   * Returns a billing account's spend limit; one that has none has no
+   * `limit`. Needs `admin.spend_limit.get` on the organization.
+   */
+  async getSpendLimit(request: GetSpendLimitRequest, options?: CallOptions): Promise<SpendLimit> {
+    const p0 = pathValue("name", request.name, "organizations/*/billingAccounts/*/spendLimit");
+    return this.service.call<SpendLimit>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Sets or removes a billing account's spend limit. The fields named in
+   * `updateMask` are replaced and the others kept. A spend limit left
+   * without a `limit` is removed, with its thresholds and recipients. Needs
+   * `admin.spend_limit.update` on the organization.
+   */
+  async updateSpendLimit(request: UpdateSpendLimitRequest, options?: CallOptions): Promise<SpendLimit> {
+    const p0 = pathValue("spendLimit.name", request.spendLimit?.name, "organizations/*/billingAccounts/*/spendLimit");
+    return this.service.call<SpendLimit>(
+      {
+        method: "PATCH",
+        path: `/v1beta1/${p0}`,
+        body: request.spendLimit,
+        query: query(request, ["spendLimit.name", "spendLimit"]),
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * A billing account's spend limit: the most it means to spend in a calendar
+ * month, and when to be told. Each threshold alerts once a month, the first
+ * time the month's spend crosses it.
+ */
+export interface SpendLimit {
+  /**
+   * The spend limit's resource name,
+   * `organizations/{organization}/billingAccounts/{billing_account}/spendLimit`.
+   */
+  name?: string;
+  /**
+   * The amount per calendar month in EUR, before VAT, as a decimal string
+   * such as `500.00`; more than zero. Unset means no spend limit.
+   */
+  limit?: string;
+  /**
+   * The percentages of `limit` whose crossing emails an alert, such as `80`
+   * and `100`; each from 1 to 32767, so a threshold can lie beyond the
+   * limit. Empty while there is no `limit`.
+   */
+  alertThresholdsPercent?: number[];
+  /**
+   * Where alerts are sent. Empty while there is no `limit`, and an alert
+   * with no recipient is sent to nobody.
+   */
+  notificationEmails?: string[];
+  /** When the spend limit was last set; unset while there is none. */
+  updateTime?: string;
+}
+
+/** The request for GetSpendLimit. */
+export interface GetSpendLimitRequest {
+  /** The spend limit to return. */
+  name?: string;
+}
+
+/** The request for UpdateSpendLimit. */
+export interface UpdateSpendLimitRequest {
+  /** The spend limit, by its name, with the fields to change. */
+  spendLimit?: SpendLimit;
+  /**
+   * The fields to change: `limit`, `alertThresholdsPercent` and
+   * `notificationEmails`. `*` is every one of them.
+   */
+  updateMask?: string;
+}