@origincloud/billing 0.0.0-stage → 0.13.0

package/src/v1beta1/billing_account.ts

@@ -0,0 +1,590 @@
+// Code generated by the SDK's generator (generator/). DO NOT EDIT.
+// source: origincloud/billing/v1beta1/billing_account.proto
+
+import {
+  type CallOptions,
+  type Client,
+  type Empty,
+  type Service,
+  newRequestId,
+  pathValue,
+  query,
+} from "@origincloud/core";
+
+/**
+ * Calls BillingAccountService.
+ *
+ * Billing accounts, which project each one pays for, and how they are paid.
+ */
+export class BillingAccountClient {
+  /**
+   * The endpoint the client sends its calls to, which also serves the
+   * operations its methods answer with.
+   */
+  readonly service: Service;
+
+  /** A client of BillingAccountService that sends its calls through `client`. */
+  constructor(client: Client) {
+    this.service = client.service("billing", false);
+  }
+
+  /**
+   * Returns a billing account. Needs `admin.billing_account.get` on the
+   * organization.
+   */
+  async getBillingAccount(request: GetBillingAccountRequest, options?: CallOptions): Promise<BillingAccount> {
+    const p0 = pathValue("name", request.name, "organizations/*/billingAccounts/*");
+    return this.service.call<BillingAccount>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Lists an organization's billing accounts, oldest first. Needs
+   * `admin.billing_account.list` on the organization.
+   */
+  async listBillingAccounts(request: ListBillingAccountsRequest, options?: CallOptions): Promise<ListBillingAccountsResponse> {
+    const p0 = pathValue("parent", request.parent, "organizations/*");
+    return this.service.call<ListBillingAccountsResponse>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}/billingAccounts`,
+        query: query(request, ["parent"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Iterates over everything listBillingAccounts 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 *allBillingAccounts(request: ListBillingAccountsRequest, options?: CallOptions): AsyncGenerator<BillingAccount, void, undefined> {
+    for (let page = request; ; ) {
+      const response = await this.listBillingAccounts(page, options);
+      yield* response.billingAccounts ?? [];
+      if (!response.nextPageToken) return;
+      page = { ...page, pageToken: response.nextPageToken };
+    }
+  }
+
+  /**
+   * Creates a billing account with its profile: `displayName`,
+   * `billingAddress`, `invoiceEmail` and `contactPerson` are required,
+   * and `vatId` too for a billing address outside Germany. The account
+   * has no payment method yet: until one is verified, the projects linked
+   * to it can't create billable resources. Creating it grants nobody a
+   * role: whoever can create billing accounts can use it. Needs
+   * `admin.billing_account.create` on the organization.
+   */
+  async createBillingAccount(request: CreateBillingAccountRequest, options?: CallOptions): Promise<BillingAccount> {
+    if (!request.requestId) request = { ...request, requestId: newRequestId() };
+    const p0 = pathValue("parent", request.parent, "organizations/*");
+    return this.service.call<BillingAccount>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}/billingAccounts`,
+        body: request.billingAccount,
+        query: query(request, ["parent", "billingAccount"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Changes a billing account's `displayName` or its profile. The profile
+   * fields named in `updateMask` are replaced and the others kept; once
+   * the update is applied, the account must have a whole profile
+   * (`billingAddress`, `invoiceEmail`, `contactPerson`, and `vatId`
+   * for a billing address outside Germany), or the update is refused. Needs
+   * `admin.billing_account.update` on the organization.
+   */
+  async updateBillingAccount(request: UpdateBillingAccountRequest, options?: CallOptions): Promise<BillingAccount> {
+    const p0 = pathValue("billingAccount.name", request.billingAccount?.name, "organizations/*/billingAccounts/*");
+    return this.service.call<BillingAccount>(
+      {
+        method: "PATCH",
+        path: `/v1beta1/${p0}`,
+        body: request.billingAccount,
+        query: query(request, ["billingAccount.name", "billingAccount"]),
+      },
+      options,
+    );
+  }
+
+  /**
+   * Deletes a billing account. Refused as a `CONFLICT` for the
+   * organization's default billing account, while a project is linked to
+   * the account (link it to another account first), and while the account
+   * has a spend limit (remove it first). Needs
+   * `admin.billing_account.delete` on the organization.
+   */
+  async deleteBillingAccount(request: DeleteBillingAccountRequest, options?: CallOptions): Promise<Empty> {
+    const p0 = pathValue("name", request.name, "organizations/*/billingAccounts/*");
+    return this.service.call<Empty>(
+      {
+        method: "DELETE",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+      },
+      options,
+    );
+  }
+
+  /**
+   * Starts adding a payment method to a billing account, and returns the
+   * payment provider's page to open in a browser: the payment details are
+   * entered there and never pass through this API. Once that page is done,
+   * call ConfirmPaymentMethodSetup. Starting again replaces a setup that
+   * wasn't confirmed. Refused as `INVALID_ARGUMENT` for an account whose
+   * `paymentMethod.state` is `NOT_REQUIRED`. Needs
+   * `admin.billing_account.update` on the organization.
+   */
+  async startPaymentMethodSetup(request: StartPaymentMethodSetupRequest, options?: CallOptions): Promise<StartPaymentMethodSetupResponse> {
+    const p0 = pathValue("name", request.name, "organizations/*/billingAccounts/*");
+    return this.service.call<StartPaymentMethodSetupResponse>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:startPaymentMethodSetup`,
+        body: request,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Completes the setup StartPaymentMethodSetup started, once its page is
+   * done: the payment provider is asked whether it finished, and only a
+   * finished setup is recorded. The account's `paymentMethod` is then
+   * `VERIFIED`, replacing any earlier one, and its projects can create
+   * billable resources. An unfinished or abandoned setup is refused as
+   * `INVALID_ARGUMENT` and changes nothing: finish the page, or start
+   * again. So is an account with no setup started, which includes a
+   * repeat of a confirmation that succeeded: read the account to see
+   * whether it did. Needs `admin.billing_account.update` on the
+   * organization.
+   */
+  async confirmPaymentMethodSetup(request: ConfirmPaymentMethodSetupRequest, options?: CallOptions): Promise<BillingAccount> {
+    const p0 = pathValue("name", request.name, "organizations/*/billingAccounts/*");
+    return this.service.call<BillingAccount>(
+      {
+        method: "POST",
+        path: `/v1beta1/${p0}:confirmPaymentMethodSetup`,
+        body: request,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Returns which billing account pays for a project. Needs
+   * `admin.project.get` on the project.
+   */
+  async getProjectBillingInfo(request: GetProjectBillingInfoRequest, options?: CallOptions): Promise<ProjectBillingInfo> {
+    const p0 = pathValue("name", request.name, "projects/*/billingInfo");
+    return this.service.call<ProjectBillingInfo>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Links a project to another billing account of its organization, which
+   * pays for its usage from then on; what it used before stays charged to
+   * the account it was linked to then. A project is always linked to one
+   * account, so there is nothing to unlink. Needs `admin.project.attach`
+   * on the project, which is separate from access to billing accounts.
+   */
+  async updateProjectBillingInfo(request: UpdateProjectBillingInfoRequest, options?: CallOptions): Promise<ProjectBillingInfo> {
+    const p0 = pathValue("projectBillingInfo.name", request.projectBillingInfo?.name, "projects/*/billingInfo");
+    return this.service.call<ProjectBillingInfo>(
+      {
+        method: "PATCH",
+        path: `/v1beta1/${p0}`,
+        body: request.projectBillingInfo,
+        query: query(request, ["projectBillingInfo.name", "projectBillingInfo"]),
+      },
+      options,
+    );
+  }
+
+  /**
+   * Lists the projects a billing account pays for, oldest first. Needs
+   * `admin.billing_account.get` on the organization.
+   */
+  async listProjectBillingInfo(request: ListProjectBillingInfoRequest, options?: CallOptions): Promise<ListProjectBillingInfoResponse> {
+    const p0 = pathValue("name", request.name, "organizations/*/billingAccounts/*");
+    return this.service.call<ListProjectBillingInfoResponse>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}/projects`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Iterates over everything listProjectBillingInfo 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 *allProjectBillingInfos(request: ListProjectBillingInfoRequest, options?: CallOptions): AsyncGenerator<ProjectBillingInfo, void, undefined> {
+    for (let page = request; ; ) {
+      const response = await this.listProjectBillingInfo(page, options);
+      yield* response.projectBillingInfos ?? [];
+      if (!response.nextPageToken) return;
+      page = { ...page, pageToken: response.nextPageToken };
+    }
+  }
+
+  /** Returns a country a billing address may be in. */
+  async getBillingCountry(request: GetBillingCountryRequest, options?: CallOptions): Promise<BillingCountry> {
+    const p0 = pathValue("name", request.name, "billingCountries/*");
+    return this.service.call<BillingCountry>(
+      {
+        method: "GET",
+        path: `/v1beta1/${p0}`,
+        query: query(request, ["name"]),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Lists the countries a billing address may be in, in the order a form
+   * shows them, and whether each needs a VAT id.
+   */
+  async listBillingCountries(request: ListBillingCountriesRequest, options?: CallOptions): Promise<ListBillingCountriesResponse> {
+    return this.service.call<ListBillingCountriesResponse>(
+      {
+        method: "GET",
+        path: `/v1beta1/billingCountries`,
+        query: query(request, []),
+        idempotent: true,
+      },
+      options,
+    );
+  }
+
+  /**
+   * Iterates over everything listBillingCountries 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 *allBillingCountries(request: ListBillingCountriesRequest, options?: CallOptions): AsyncGenerator<BillingCountry, void, undefined> {
+    for (let page = request; ; ) {
+      const response = await this.listBillingCountries(page, options);
+      yield* response.billingCountries ?? [];
+      if (!response.nextPageToken) return;
+      page = { ...page, pageToken: response.nextPageToken };
+    }
+  }
+}
+
+/**
+ * An organization's billing account: who invoices are issued to, and how
+ * its projects' usage is paid.
+ */
+export interface BillingAccount {
+  /** The billing account's resource name. */
+  name?: string;
+  /**
+   * The billing account's URN, the identifier access policies and the audit
+   * log use.
+   */
+  urn?: string;
+  /**
+   * The name the console and spend-limit alerts show. Not empty. An
+   * organization's default account is called `default` until it is
+   * renamed.
+   */
+  displayName?: string;
+  /**
+   * Whether this is the organization's default billing account: the one
+   * its new projects are linked to. Every organization has exactly one,
+   * and it can't be deleted.
+   */
+  defaultAccount?: boolean;
+  /**
+   * The postal address invoices are issued to. Required to create an
+   * account; unset only on an organization's default account until its
+   * profile is set.
+   */
+  billingAddress?: BillingAddress;
+  /**
+   * Where invoices are sent. Required to create an account; empty only on
+   * an organization's default account until its profile is set.
+   */
+  invoiceEmail?: string;
+  /**
+   * The VAT identification number invoices name; empty for none. Required
+   * for a billing address outside Germany.
+   */
+  vatId?: string;
+  /**
+   * Who invoices are addressed to. Required to create an account; empty
+   * only on an organization's default account until its profile is set.
+   */
+  contactPerson?: string;
+  /** How the account is paid. */
+  paymentMethod?: PaymentMethod;
+  /** When the billing account was created. */
+  createTime?: string;
+  /**
+   * The principal that created the billing account, such as `user:<id>` or
+   * `service_account:<id>`.
+   */
+  creator?: string;
+}
+
+/** A postal address invoices are issued to. Every field is required. */
+export interface BillingAddress {
+  /** The street and house number. */
+  street?: string;
+  /** The city. */
+  city?: string;
+  /** The postal code. */
+  postalCode?: string;
+  /**
+   * The country, as the ISO 3166-1 alpha-2 code of one of the countries
+   * ListBillingCountries lists, such as `DE`.
+   */
+  regionCode?: string;
+}
+
+/**
+ * How a billing account is paid. Only the payment method's kind and the
+ * last digits of a card are shown; the payment details themselves stay
+ * with the payment provider.
+ */
+export interface PaymentMethod {
+  /** Whether the account can pay for usage. */
+  state?: PaymentMethod_State;
+  /**
+   * The verified card's brand, such as `visa`; empty while no payment
+   * method is verified, and for one that isn't a card.
+   */
+  cardBrand?: string;
+  /**
+   * The verified card's last four digits; empty while no payment method is
+   * verified, and for one that isn't a card.
+   */
+  cardLast4?: string;
+}
+
+/** Whether the account can pay for usage. */
+export const PaymentMethod_State = {
+  /** Not set. */
+  STATE_UNSPECIFIED: "STATE_UNSPECIFIED",
+  /**
+   * No verified payment method: the projects linked to the account can't
+   * create billable resources until one is added with
+   * StartPaymentMethodSetup and ConfirmPaymentMethodSetup.
+   */
+  MISSING: "MISSING",
+  /** A payment method is verified, and billable resources can be created. */
+  VERIFIED: "VERIFIED",
+  /**
+   * The account is invoiced by arrangement with the platform's operator:
+   * it needs no payment method, and the setup methods are refused.
+   */
+  NOT_REQUIRED: "NOT_REQUIRED",
+} as const;
+
+/** Whether the account can pay for usage. */
+export type PaymentMethod_State = (typeof PaymentMethod_State)[keyof typeof PaymentMethod_State];
+
+/** Which billing account pays for a project. */
+export interface ProjectBillingInfo {
+  /** The billing info's resource name, `projects/{project}/billingInfo`. */
+  name?: string;
+  /**
+   * The billing account that pays for the project's usage, one of its
+   * organization's.
+   */
+  billingAccount?: string;
+}
+
+/** A country a billing address may be in. */
+export interface BillingCountry {
+  /** The country's resource name, `billingCountries/{code}`. */
+  name?: string;
+  /**
+   * The ISO 3166-1 alpha-2 code a billing address names it by, such as
+   * `DE`.
+   */
+  regionCode?: string;
+  /** The country's name in English. */
+  displayName?: string;
+  /**
+   * Whether a billing account with an address in this country needs a
+   * `vatId`. Customers in every country but Germany are invoiced without
+   * VAT, as businesses under the reverse-charge rule, which needs one.
+   */
+  vatIdRequired?: boolean;
+}
+
+/** The request for GetBillingAccount. */
+export interface GetBillingAccountRequest {
+  /** The billing account to return. */
+  name?: string;
+}
+
+/** The request for ListBillingAccounts. */
+export interface ListBillingAccountsRequest {
+  /**
+   * The organization whose billing accounts to list,
+   * `organizations/{organization}`.
+   */
+  parent?: string;
+  /**
+   * The most billing accounts 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 ListBillingAccounts. */
+export interface ListBillingAccountsResponse {
+  /** The billing accounts on this page. */
+  billingAccounts?: BillingAccount[];
+  /** The token for the next page; empty on the last one. */
+  nextPageToken?: string;
+}
+
+/** The request for CreateBillingAccount. */
+export interface CreateBillingAccountRequest {
+  /**
+   * The organization to create the billing account in,
+   * `organizations/{organization}`.
+   */
+  parent?: string;
+  /** The billing account to create: its `displayName` and profile. */
+  billingAccount?: BillingAccount;
+  /**
+   * A UUID; a repeat with the same id returns the billing account the first
+   * request created instead of creating a second one.
+   */
+  requestId?: string;
+}
+
+/** The request for UpdateBillingAccount. */
+export interface UpdateBillingAccountRequest {
+  /** The billing account, by its name, with the fields to change. */
+  billingAccount?: BillingAccount;
+  /**
+   * The fields to change: `displayName`, `billingAddress`,
+   * `invoiceEmail`, `vatId` and `contactPerson`. `*` is every one of
+   * them.
+   */
+  updateMask?: string;
+}
+
+/** The request for DeleteBillingAccount. */
+export interface DeleteBillingAccountRequest {
+  /** The billing account to delete. */
+  name?: string;
+}
+
+/** The request for StartPaymentMethodSetup. */
+export interface StartPaymentMethodSetupRequest {
+  /** The billing account to add a payment method to. */
+  name?: string;
+}
+
+/** The response for StartPaymentMethodSetup. */
+export interface StartPaymentMethodSetupResponse {
+  /**
+   * The payment provider's page to open in a browser, where the payment
+   * details are entered. It returns to the console when done.
+   */
+  redirectUri?: string;
+}
+
+/** The request for ConfirmPaymentMethodSetup. */
+export interface ConfirmPaymentMethodSetupRequest {
+  /** The billing account whose setup to complete. */
+  name?: string;
+}
+
+/** The request for GetProjectBillingInfo. */
+export interface GetProjectBillingInfoRequest {
+  /** The billing info to return, `projects/{project}/billingInfo`. */
+  name?: string;
+}
+
+/** The request for UpdateProjectBillingInfo. */
+export interface UpdateProjectBillingInfoRequest {
+  /** The billing info, by its name, with the billing account to link. */
+  projectBillingInfo?: ProjectBillingInfo;
+  /** The fields to change: `billingAccount`. `*` is the same. */
+  updateMask?: string;
+}
+
+/** The request for ListProjectBillingInfo. */
+export interface ListProjectBillingInfoRequest {
+  /** The billing account whose projects to list. */
+  name?: string;
+  /**
+   * The most projects 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 ListProjectBillingInfo. */
+export interface ListProjectBillingInfoResponse {
+  /** The billing info of each project on this page. */
+  projectBillingInfos?: ProjectBillingInfo[];
+  /** The token for the next page; empty on the last one. */
+  nextPageToken?: string;
+}
+
+/** The request for GetBillingCountry. */
+export interface GetBillingCountryRequest {
+  /**
+   * The country to return, `billingCountries/{code}`, such as
+   * `billingCountries/DE`.
+   */
+  name?: string;
+}
+
+/** The request for ListBillingCountries. */
+export interface ListBillingCountriesRequest {
+  /**
+   * The most countries 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 ListBillingCountries. */
+export interface ListBillingCountriesResponse {
+  /** The countries on this page. */
+  billingCountries?: BillingCountry[];
+  /** The token for the next page; empty on the last one. */
+  nextPageToken?: string;
+}