@vertracloud/api-types 0.3.1 → 0.3.3

package/rest/v1/billing.d.ts

@@ -2,24 +2,25 @@ import { APIPayload } from '../../common/v1.js';
 import { APIBillingCard, APIBillingDetails, APIBillingRenewal, APIBillingAddress, BillingTaxIdType } from '../../payloads/v1/billing.js';
 import '../../payloads/v1/api-error.js';
 
-/** `GET /v1/users/me/billing` — Dashboard session only. `response` is `null` until details are saved. */
+/** `GET /v1/users/me/billing` — API key scope `billing:read`. `response` is `null` until details are saved. */
 type RESTGetAPIBillingDetailsResponse = APIPayload<APIBillingDetails | null>;
 /**
- * `PUT /v1/users/me/billing` — Dashboard session only. Replaces the billing details.
+ * `PUT /v1/users/me/billing` — API key scope `billing:write`. Replaces the billing details.
  * Fails with 400 `BILLING_DETAILS_INVALID` (the field in `details.path`), 400 `TAX_ID_INVALID` and
  * 400 `PAYMENT_METHOD_UNAVAILABLE` when online payments are not available.
  */
 interface RESTPutAPIBillingDetailsBody {
     name: string;
     address: APIBillingAddress;
-    phone: string;
+    /** Optional. E.164. `null` or omitted removes the saved phone. */
+    phone?: string | null;
     /** Optional. `null` removes the saved document; omitting it keeps the saved one. */
     tax_id?: {
         type: BillingTaxIdType;
         value: string;
     } | null;
 }
-/** `PUT /v1/users/me/billing` — Dashboard session only. */
+/** `PUT /v1/users/me/billing` — API key scope `billing:write`. */
 type RESTPutAPIBillingDetailsResponse = APIPayload<APIBillingDetails>;
 /** `GET /v1/users/me/cards` — Dashboard session only. Default card first. */
 type RESTGetAPIBillingCardsResponse = APIPayload<APIBillingCard[]>;

package/rest/v1/billing.js.map

@@ -1 +1 @@
-{"version":3,"sources":["billing.ts"],"sourcesContent":["import type { APIBillingAddress, APIBillingCard, APIBillingDetails, APIBillingRenewal, APIPayload, BillingTaxIdType } from \"../../v1\";\n\n/** `GET /v1/users/me/billing` — Dashboard session only. `response` is `null` until details are saved. */\nexport type RESTGetAPIBillingDetailsResponse = APIPayload<APIBillingDetails | null>;\n\n/**\n * `PUT /v1/users/me/billing` — Dashboard session only. Replaces the billing details.\n * Fails with 400 `BILLING_DETAILS_INVALID` (the field in `details.path`), 400 `TAX_ID_INVALID` and\n * 400 `PAYMENT_METHOD_UNAVAILABLE` when online payments are not available.\n */\nexport interface RESTPutAPIBillingDetailsBody {\n\tname: string;\n\taddress: APIBillingAddress;\n\tphone: string;\n\t/** Optional. `null` removes the saved document; omitting it keeps the saved one. */\n\ttax_id?: { type: BillingTaxIdType; value: string } | null;\n}\n\n/** `PUT /v1/users/me/billing` — Dashboard session only. */\nexport type RESTPutAPIBillingDetailsResponse = APIPayload<APIBillingDetails>;\n\n/** `GET /v1/users/me/cards` — Dashboard session only. Default card first. */\nexport type RESTGetAPIBillingCardsResponse = APIPayload<APIBillingCard[]>;\n\n/**\n * `POST /v1/users/me/cards/setup` — Dashboard session only. Secret that saves a new card in the\n * browser. The card shows up in `GET /v1/users/me/cards` once confirmed; the first card becomes the default.\n * 400 `PAYMENT_METHOD_UNAVAILABLE` when online payments are not available.\n */\nexport type RESTPostAPIBillingCardSetupResponse = APIPayload<{ client_secret: string }>;\n\n/** `POST /v1/users/me/cards/:cardId/default` — Dashboard session only. 404 `CARD_NOT_FOUND`. */\nexport type RESTPostAPIBillingCardDefaultResponse = APIPayload<APIBillingCard[]>;\n\n/**\n * `DELETE /v1/users/me/cards/:cardId` — Dashboard session only. 404 `CARD_NOT_FOUND`.\n * Removing the default card makes the most recent remaining card the default; without cards,\n * the plan no longer renews automatically. 400 `PAYMENT_METHOD_UNAVAILABLE` when online payments are\n * not available.\n */\nexport type RESTDeleteAPIBillingCardResponse = APIPayload<null>;\n\n/** `GET /v1/users/me/billing/renewal` — Dashboard session only. */\nexport type RESTGetAPIBillingRenewalResponse = APIPayload<APIBillingRenewal>;\n\n/** `PATCH /v1/users/me/billing/renewal` — Dashboard session only. 400 `INVALID_PAYLOAD` for a malformed body. */\nexport interface RESTPatchAPIBillingRenewalBody {\n\t/** `false` cancels the automatic renewal (no charge is made later); `true` turns it back on. */\n\tauto_renew: boolean;\n}\n\n/** `PATCH /v1/users/me/billing/renewal` — Dashboard session only. */\nexport type RESTPatchAPIBillingRenewalResponse = APIPayload<APIBillingRenewal>;\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["billing.ts"],"sourcesContent":["import type { APIBillingAddress, APIBillingCard, APIBillingDetails, APIBillingRenewal, APIPayload, BillingTaxIdType } from \"../../v1\";\n\n/** `GET /v1/users/me/billing` — API key scope `billing:read`. `response` is `null` until details are saved. */\nexport type RESTGetAPIBillingDetailsResponse = APIPayload<APIBillingDetails | null>;\n\n/**\n * `PUT /v1/users/me/billing` — API key scope `billing:write`. Replaces the billing details.\n * Fails with 400 `BILLING_DETAILS_INVALID` (the field in `details.path`), 400 `TAX_ID_INVALID` and\n * 400 `PAYMENT_METHOD_UNAVAILABLE` when online payments are not available.\n */\nexport interface RESTPutAPIBillingDetailsBody {\n\tname: string;\n\taddress: APIBillingAddress;\n\t/** Optional. E.164. `null` or omitted removes the saved phone. */\n\tphone?: string | null;\n\t/** Optional. `null` removes the saved document; omitting it keeps the saved one. */\n\ttax_id?: { type: BillingTaxIdType; value: string } | null;\n}\n\n/** `PUT /v1/users/me/billing` — API key scope `billing:write`. */\nexport type RESTPutAPIBillingDetailsResponse = APIPayload<APIBillingDetails>;\n\n/** `GET /v1/users/me/cards` — Dashboard session only. Default card first. */\nexport type RESTGetAPIBillingCardsResponse = APIPayload<APIBillingCard[]>;\n\n/**\n * `POST /v1/users/me/cards/setup` — Dashboard session only. Secret that saves a new card in the\n * browser. The card shows up in `GET /v1/users/me/cards` once confirmed; the first card becomes the default.\n * 400 `PAYMENT_METHOD_UNAVAILABLE` when online payments are not available.\n */\nexport type RESTPostAPIBillingCardSetupResponse = APIPayload<{ client_secret: string }>;\n\n/** `POST /v1/users/me/cards/:cardId/default` — Dashboard session only. 404 `CARD_NOT_FOUND`. */\nexport type RESTPostAPIBillingCardDefaultResponse = APIPayload<APIBillingCard[]>;\n\n/**\n * `DELETE /v1/users/me/cards/:cardId` — Dashboard session only. 404 `CARD_NOT_FOUND`.\n * Removing the default card makes the most recent remaining card the default; without cards,\n * the plan no longer renews automatically. 400 `PAYMENT_METHOD_UNAVAILABLE` when online payments are\n * not available.\n */\nexport type RESTDeleteAPIBillingCardResponse = APIPayload<null>;\n\n/** `GET /v1/users/me/billing/renewal` — Dashboard session only. */\nexport type RESTGetAPIBillingRenewalResponse = APIPayload<APIBillingRenewal>;\n\n/** `PATCH /v1/users/me/billing/renewal` — Dashboard session only. 400 `INVALID_PAYLOAD` for a malformed body. */\nexport interface RESTPatchAPIBillingRenewalBody {\n\t/** `false` cancels the automatic renewal (no charge is made later); `true` turns it back on. */\n\tauto_renew: boolean;\n}\n\n/** `PATCH /v1/users/me/billing/renewal` — Dashboard session only. */\nexport type RESTPatchAPIBillingRenewalResponse = APIPayload<APIBillingRenewal>;\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/rest/v1/user.d.ts

@@ -22,6 +22,7 @@ interface RESTPatchAPIUserMeBody {
     name?: string;
     language?: UserLanguage;
     workspace_invites_enabled?: boolean;
+    marketing_emails_enabled?: boolean;
 }
 type RESTPatchAPIUserMeResponse = APIPayload<APIUser>;
 interface RESTPostAPIUserResourceFolderBody {

package/rest/v1/user.js.map

@@ -1 +1 @@
-{"version":3,"sources":["user.ts"],"sourcesContent":["import type { APIPaginatedPayload, APIPayload, APIUser, APIUserApiKey, APIUserApiKeyRequestEvent, APIUserInfoResponse, APIUserSession, ISODateString, UserLanguage } from \"../../v1\";\nimport type { APIWorkspaceResourceFolder, APIWorkspaceResourceOrganization, WorkspaceFolderColor } from \"../../v1\";\n\n/**\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/me\n */\nexport type RESTGetAPIUserInfoResponse = APIPayload<APIUserInfoResponse>;\n\n/**\n * `POST /v1/users/me/downgrade` — dashboard session only.\n * @see https://docs.vertracloud.app/plan-downgrade\n */\nexport type RESTPostAPIUserDowngradeResponse = APIPayload<APIUser>;\n\n/**\n * `PATCH /v1/users/me`.\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/update-me\n */\nexport interface RESTPatchAPIUserMeBody {\n\tname?: string;\n\tlanguage?: UserLanguage;\n\tworkspace_invites_enabled?: boolean;\n}\nexport type RESTPatchAPIUserMeResponse = APIPayload<APIUser>;\n\nexport interface RESTPostAPIUserResourceFolderBody {\n\tname: string;\n\tcolor?: WorkspaceFolderColor;\n\tposition?: number;\n}\nexport type RESTPostAPIUserResourceFolderResponse = APIPayload<APIWorkspaceResourceFolder>;\nexport interface RESTPatchAPIUserResourceFolderBody {\n\tname?: string;\n\tcolor?: WorkspaceFolderColor;\n\tposition?: number;\n}\nexport type RESTPatchAPIUserResourceFolderResponse = APIPayload<APIWorkspaceResourceFolder>;\nexport type RESTDeleteAPIUserResourceFolderResponse = APIPayload<null>;\nexport interface RESTPutAPIUserResourceFolderResourceBody {\n\tposition?: number;\n}\nexport type RESTPutAPIUserResourceFolderResourceResponse = APIPayload<APIWorkspaceResourceOrganization>;\nexport type RESTDeleteAPIUserResourceFolderResourceResponse = APIPayload<APIWorkspaceResourceOrganization>;\nexport interface RESTPutAPIUserFavoriteBody {\n\tposition?: number;\n}\nexport type RESTPutAPIUserFavoriteResponse = APIPayload<APIWorkspaceResourceOrganization>;\nexport type RESTDeleteAPIUserFavoriteResponse = APIPayload<APIWorkspaceResourceOrganization>;\n\n/**\n * Legacy CLI route; prefer the API key management under `/v1/users/me/api-keys`.\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/api-keys/create\n */\nexport type RESTPostAPIUserGenerateApiKeyResponse = APIPayload<APIUserApiKey>;\n\n/**\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/sessions\n */\nexport type RESTGetAPIUserSessionsResponse = APIPayload<APIUserSession[]>;\n\n/**\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/api-key-requests\n */\nexport interface RESTGetAPIUserApiKeyRequestsQuery {\n\t/** Filters by key (`APIApiKey.id`). */\n\tapi_key_id?: string;\n\tfrom?: ISODateString;\n\tto?: ISODateString;\n\tpage?: number;\n\tper_page?: number;\n\terrors_only?: boolean;\n}\n\nexport type RESTGetAPIUserApiKeyRequestsResponse = APIPaginatedPayload<APIUserApiKeyRequestEvent>;\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["user.ts"],"sourcesContent":["import type { APIPaginatedPayload, APIPayload, APIUser, APIUserApiKey, APIUserApiKeyRequestEvent, APIUserInfoResponse, APIUserSession, ISODateString, UserLanguage } from \"../../v1\";\nimport type { APIWorkspaceResourceFolder, APIWorkspaceResourceOrganization, WorkspaceFolderColor } from \"../../v1\";\n\n/**\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/me\n */\nexport type RESTGetAPIUserInfoResponse = APIPayload<APIUserInfoResponse>;\n\n/**\n * `POST /v1/users/me/downgrade` — dashboard session only.\n * @see https://docs.vertracloud.app/plan-downgrade\n */\nexport type RESTPostAPIUserDowngradeResponse = APIPayload<APIUser>;\n\n/**\n * `PATCH /v1/users/me`.\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/update-me\n */\nexport interface RESTPatchAPIUserMeBody {\n\tname?: string;\n\tlanguage?: UserLanguage;\n\tworkspace_invites_enabled?: boolean;\n\tmarketing_emails_enabled?: boolean;\n}\nexport type RESTPatchAPIUserMeResponse = APIPayload<APIUser>;\n\nexport interface RESTPostAPIUserResourceFolderBody {\n\tname: string;\n\tcolor?: WorkspaceFolderColor;\n\tposition?: number;\n}\nexport type RESTPostAPIUserResourceFolderResponse = APIPayload<APIWorkspaceResourceFolder>;\nexport interface RESTPatchAPIUserResourceFolderBody {\n\tname?: string;\n\tcolor?: WorkspaceFolderColor;\n\tposition?: number;\n}\nexport type RESTPatchAPIUserResourceFolderResponse = APIPayload<APIWorkspaceResourceFolder>;\nexport type RESTDeleteAPIUserResourceFolderResponse = APIPayload<null>;\nexport interface RESTPutAPIUserResourceFolderResourceBody {\n\tposition?: number;\n}\nexport type RESTPutAPIUserResourceFolderResourceResponse = APIPayload<APIWorkspaceResourceOrganization>;\nexport type RESTDeleteAPIUserResourceFolderResourceResponse = APIPayload<APIWorkspaceResourceOrganization>;\nexport interface RESTPutAPIUserFavoriteBody {\n\tposition?: number;\n}\nexport type RESTPutAPIUserFavoriteResponse = APIPayload<APIWorkspaceResourceOrganization>;\nexport type RESTDeleteAPIUserFavoriteResponse = APIPayload<APIWorkspaceResourceOrganization>;\n\n/**\n * Legacy CLI route; prefer the API key management under `/v1/users/me/api-keys`.\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/api-keys/create\n */\nexport type RESTPostAPIUserGenerateApiKeyResponse = APIPayload<APIUserApiKey>;\n\n/**\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/sessions\n */\nexport type RESTGetAPIUserSessionsResponse = APIPayload<APIUserSession[]>;\n\n/**\n * @see https://docs.vertracloud.app/api-reference/endpoint/users/api-key-requests\n */\nexport interface RESTGetAPIUserApiKeyRequestsQuery {\n\t/** Filters by key (`APIApiKey.id`). */\n\tapi_key_id?: string;\n\tfrom?: ISODateString;\n\tto?: ISODateString;\n\tpage?: number;\n\tper_page?: number;\n\terrors_only?: boolean;\n}\n\nexport type RESTGetAPIUserApiKeyRequestsResponse = APIPaginatedPayload<APIUserApiKeyRequestEvent>;\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/v1.js

@@ -329,15 +329,20 @@ var API_KEY_SCOPES = {
     group: "billing",
     routes: [
       { method: "GET", path: "/v1/orders" },
-      { method: "GET", path: "/v1/orders/:orderId/status" }
+      { method: "GET", path: "/v1/orders/:orderId/status" },
+      { method: "GET", path: "/v1/users/me/billing" }
     ]
   },
-  /** Creates a plan order and generates the PIX charge; the payment itself is made by a person in their banking app. */
+  /**
+   * Creates a plan order and generates the PIX charge; the payment itself is made by a person in their banking app.
+   * Also saves the billing details (name, address, CPF/CNPJ) an order needs.
+   */
   "billing:write": {
     group: "billing",
     routes: [
       { method: "POST", path: "/v1/orders" },
-      { method: "POST", path: "/v1/orders/:orderId/initiate/pix" }
+      { method: "POST", path: "/v1/orders/:orderId/initiate/pix" },
+      { method: "PUT", path: "/v1/users/me/billing" }
     ]
   },
   "redeem:write": { group: "billing", routes: [{ method: "POST", path: "/v1/redeem/:code" }] }
@@ -489,6 +494,8 @@ var API_ERROR_CODES = {
   APP_NOT_FOUND_IN_WORKSPACE: "APP_NOT_FOUND_IN_WORKSPACE",
   BUILD_FAILED: "BUILD_FAILED",
   BUILD_TIMEOUT: "BUILD_TIMEOUT",
+  /** 400 — the order needs complete billing details for the service invoice (name, address and, in Brazil, CPF/CNPJ). Fill them with `PUT /v1/users/me/billing`. */
+  BILLING_DETAILS_INCOMPLETE: "BILLING_DETAILS_INCOMPLETE",
   /** 400 — billing details failed validation; the field is in `details.path`. */
   BILLING_DETAILS_INVALID: "BILLING_DETAILS_INVALID",
   /** 402 — the bank refused the card charge. */