@greensecurity/javascript-sdk 0.46.0-beta.7 → 0.46.0-beta.9

package/src/funcs/appsRotateAppWebhookEndpointSecret.ts

@@ -0,0 +1,201 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { GreenSecurityCore } from "../core.js";
+import { encodeJSON } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import * as components from "../models/components/index.js";
+import { GreenSecurityError } from "../models/errors/greensecurityerror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import * as operations from "../models/operations/index.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Rotate your app's webhook signing secret
+ *
+ * @remarks
+ * Issues a new signing secret for your app's own webhook endpoint (the one its manifest's
+ * `webhooks` declares) and returns it. This is the only way to obtain the secret, and the only
+ * response that ever carries it.
+ *
+ * Call it once after the first publish that adds `webhooks`: the endpoint is created with a
+ * secret nobody has seen, so deliveries fail your signature check until you rotate. Each retry
+ * is signed again when it is sent, so a delivery still being retried (for about 50 minutes after
+ * it was first sent) verifies once you have the new secret; reconcile anything older with
+ * `GET /marketplace/activations`. Call it again whenever you want to replace the secret or have lost it. After the
+ * first rotation, the secret being replaced keeps signing for 24 hours, next to the new one, so
+ * you can deploy the new secret without rejecting deliveries already on their way.
+ *
+ * Changing `webhooks.url` or `webhooks.events` in a later publish keeps the secret.
+ *
+ * **Permissions.** Accepts only the app service account's own unscoped token, as
+ * `Authorization: Bearer`: its permanent token, or an access token from `client_credentials`
+ * issued without `activation_id` or `scope`. App tokens (`gsu_`, `gsi_`, `gsd_`, and the
+ * `gsdr_` refresh token) and a token narrowed with `scope` are refused with `403`. A `token`
+ * query parameter is refused with `401`, even alongside the header. An app the caller is not the
+ * service account of reads as `404`, the same as one that does not exist.
+ *
+ * If set, this operation will use {@link Security.bearerJwt} from the global security.
+ */
+export function appsRotateAppWebhookEndpointSecret(
+  client: GreenSecurityCore,
+  request:
+    operations.RotateAppWebhookEndpointSecretRotateAppWebhookEndpointSecretRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    components.AppWebhookEndpointSecret,
+    | errors.ApiErrorResponse
+    | errors.UnprocessableEntityOrValidationError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request:
+    operations.RotateAppWebhookEndpointSecretRotateAppWebhookEndpointSecretRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      components.AppWebhookEndpointSecret,
+      | errors.ApiErrorResponse
+      | errors.UnprocessableEntityOrValidationError
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) =>
+      operations
+        .RotateAppWebhookEndpointSecretRotateAppWebhookEndpointSecretRequest$outboundSchema
+        .parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = encodeJSON("body", payload, { explode: true });
+
+  const path = pathToFunc("/marketplace/webhook-endpoint/secret")();
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput, [1]);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "rotateAppWebhookEndpointSecret",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.security,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    components.AppWebhookEndpointSecret,
+    | errors.ApiErrorResponse
+    | errors.UnprocessableEntityOrValidationError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, components.AppWebhookEndpointSecret$inboundSchema),
+    M.jsonErr([400, 401, 403, 404], errors.ApiErrorResponse$inboundSchema),
+    M.jsonErr(422, errors.UnprocessableEntityOrValidationError$inboundSchema),
+    M.fail("4XX"),
+    M.fail([500, "5XX"]),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/appsSetAppSecret.ts

@@ -0,0 +1,218 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { GreenSecurityCore } from "../core.js";
+import { encodeJSON } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import * as components from "../models/components/index.js";
+import { GreenSecurityError } from "../models/errors/greensecurityerror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Set an app secret
+ *
+ * @remarks
+ * Creates a secret, or replaces the payload and expiry of the secret with the same `name`
+ * in the same scope. Secrets are encrypted at rest and belong to one activation of your
+ * app: the app token's own activation, or the `activation_id` the service account sends.
+ * Removing that activation, or changing what it covers (its app, or the site, system,
+ * facility, company or user it is installed for), deletes all of its secrets.
+ *
+ * Each scope holds at most 25 secrets, and a payload is at most 8192 bytes once UTF-8
+ * encoded (fewer characters than that if it has multi-byte ones). `expires_at`, when
+ * given, must be in the future and less than 100 years away.
+ *
+ * **Permissions.** Send one of these as `Authorization: Bearer`; any other token is refused
+ * with `403`.
+ *
+ * - **An app token**: an app user token (`gsu_`) or an app installation token (`gsi_`). The
+ *   activation comes from the token, so leave `activation_id` out; if you send it, it must be
+ *   the token's own activation (`403` otherwise). Either token may write to the `installation`
+ *   scope. For the `user` scope:
+ *   - an app user token reaches only its own user (`user_id` may be left out);
+ *   - an installation token the host minted for one of your views reaches only that view's
+ *     viewer (`user_id` may be left out);
+ *   - an installation token from `client_credentials` reaches any user its activation
+ *     covers, and `user_id` is required.
+ * - **Your app's service account**: its permanent token, or a short-lived OAuth access token
+ *   issued to it without `scope` (by `client_credentials` without `activation_id`, or by the
+ *   `refresh_token` grant). A token issued with `scope` is refused with `403`, and any other
+ *   kind of token, such as a one-time sign-in link token, with `403` "This kind of token may
+ *   not access app secrets". It has no activation of its own, so `activation_id` is required
+ *   (`422` without it) and must be one of your app's activations (`403` otherwise). Its `user`
+ *   scope reaches any user the activation covers, and `user_id` is required.
+ *
+ * A `user_id` that does not exist and one the token may not reach get the same `403` "This
+ * credential may not access secrets of that user", so the endpoint never reveals which user
+ * ids exist.
+ *
+ * Whatever the token, your app must hold the platform permission `app_secrets.write`: list
+ * it in the manifest's `permissions` and upload. Until then every Secret Store call is
+ * refused with `403` "This app has not been granted app_secrets.write." For the service
+ * account this is checked before `activation_id` is looked at, so an app without the
+ * permission gets that answer whether or not it sent an `activation_id`.
+ *
+ * Every response carries `Cache-Control: no-store`, errors included, so no cache keeps a
+ * secret.
+ *
+ * If set, this operation will use {@link Security.bearerJwt} from the global security.
+ */
+export function appsSetAppSecret(
+  client: GreenSecurityCore,
+  request: components.AppSecretSetRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    components.AppSecret,
+    | errors.ApiErrorResponse
+    | errors.AppSecretsUnprocessable
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request: components.AppSecretSetRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      components.AppSecret,
+      | errors.ApiErrorResponse
+      | errors.AppSecretsUnprocessable
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) => components.AppSecretSetRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = encodeJSON("body", payload, { explode: true });
+
+  const path = pathToFunc("/apps/secrets")();
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+
+  const securityInput = await extractSecurity(client._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput, [1]);
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "setAppSecret",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: requestSecurity,
+
+    securitySource: client._options.security,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    security: requestSecurity,
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    components.AppSecret,
+    | errors.ApiErrorResponse
+    | errors.AppSecretsUnprocessable
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, components.AppSecret$inboundSchema),
+    M.jsonErr([400, 401, 403], errors.ApiErrorResponse$inboundSchema),
+    M.jsonErr(422, errors.AppSecretsUnprocessable$inboundSchema),
+    M.jsonErr(500, errors.ApiErrorResponse$inboundSchema),
+    M.fail("4XX"),
+    M.fail("5XX"),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}

package/src/funcs/companiesLookupCompanies.ts

@@ -38,6 +38,9 @@ import {
  * @remarks
  * Lists companies available to the caller as minimal lookup summaries for list and typeahead UIs.
  *
+ * For a vendor, the list holds the active companies on the vendor's site: the companies the
+ * vendor can add as managing companies. Other callers see the companies they can view.
+ *
  * **Permissions.** Requires the `companies.view` permission.
  *
  * If set, this operation will use {@link Security.bearerJwt} from the global security.

package/src/funcs/oauthCreateDeviceAuthorization.ts

@@ -0,0 +1,182 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { GreenSecurityCore } from "../core.js";
+import { encodeJSON } from "../lib/encodings.js";
+import { matchStatusCode } from "../lib/http.js";
+import * as M from "../lib/matchers.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { pathToFunc } from "../lib/url.js";
+import * as components from "../models/components/index.js";
+import { GreenSecurityError } from "../models/errors/greensecurityerror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * Start a device login
+ *
+ * @remarks
+ * Starts the RFC 8628 device authorization flow that `apps-cli login` uses:
+ *
+ * 1. Call this endpoint and show the user `user_code`, or open `verification_uri_complete`.
+ * 2. The user approves the request in the Green Security app, signed in as themselves.
+ * 3. Meanwhile, poll `POST /oauth/token` with
+ *    `grant_type=urn:ietf:params:oauth:grant-type:device_code` every `interval` seconds.
+ *    It answers `authorization_pending` until the user approves, and then returns a
+ *    15-minute developer CLI token and a refresh token that renews it, for up to 90 days.
+ *
+ * The codes expire after `expires_in` seconds. Each address may start 20 logins per ten
+ * minutes; past that the endpoint answers `429` with `slow_down`. The request body may be
+ * JSON or `application/x-www-form-urlencoded`.
+ *
+ * Every response, errors included, carries `Cache-Control: no-store` and `Pragma: no-cache`
+ * (RFC 6749 section 5.1), so no cache keeps a token or code.
+ *
+ * **Permissions.** No authentication required.
+ */
+export function oauthCreateDeviceAuthorization(
+  client: GreenSecurityCore,
+  request: components.DeviceAuthorizationRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    components.DeviceAuthorizationResponse,
+    | errors.OAuthError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >
+> {
+  return new APIPromise($do(
+    client,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client: GreenSecurityCore,
+  request: components.DeviceAuthorizationRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      components.DeviceAuthorizationResponse,
+      | errors.OAuthError
+      | GreenSecurityError
+      | ResponseValidationError
+      | ConnectionError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | InvalidRequestError
+      | UnexpectedClientError
+      | SDKValidationError
+    >,
+    APICall,
+  ]
+> {
+  const parsed = safeParse(
+    request,
+    (value) =>
+      components.DeviceAuthorizationRequest$outboundSchema.parse(value),
+    "Input validation failed",
+  );
+  if (!parsed.ok) {
+    return [parsed, { status: "invalid" }];
+  }
+  const payload = parsed.value;
+  const body = encodeJSON("body", payload, { explode: true });
+
+  const path = pathToFunc("/oauth/device_authorization")();
+
+  const headers = new Headers(compactMap({
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  }));
+
+  const context = {
+    options: client._options,
+    baseURL: options?.serverURL ?? client._baseURL ?? "",
+    operationID: "createDeviceAuthorization",
+    oAuth2Scopes: null,
+
+    resolvedSecurity: null,
+
+    securitySource: null,
+    retryConfig: options?.retries
+      || client._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || ["429", "500", "502", "503", "504"],
+  };
+
+  const requestRes = client._createRequest(context, {
+    method: "POST",
+    baseURL: options?.serverURL,
+    path: path,
+    headers: headers,
+    body: body,
+    userAgent: client._options.userAgent,
+    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req = requestRes.value;
+
+  const doResult = await client._do(req, {
+    context,
+    isErrorStatusCode: (statusCode: number) =>
+      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req }];
+  }
+  const response = doResult.value;
+
+  const responseFields = {
+    HttpMeta: { Response: response, Request: req },
+  };
+
+  const [result] = await M.match<
+    components.DeviceAuthorizationResponse,
+    | errors.OAuthError
+    | GreenSecurityError
+    | ResponseValidationError
+    | ConnectionError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | InvalidRequestError
+    | UnexpectedClientError
+    | SDKValidationError
+  >(
+    M.json(200, components.DeviceAuthorizationResponse$inboundSchema),
+    M.jsonErr([400, 401, 429], errors.OAuthError$inboundSchema),
+    M.fail("4XX"),
+    M.fail([500, "5XX"]),
+  )(response, req, { extraFields: responseFields });
+  if (!result.ok) {
+    return [result, { status: "complete", request: req, response }];
+  }
+
+  return [result, { status: "complete", request: req, response }];
+}