@temporalio/cloud 1.11.3

package/LICENSE.md

@@ -0,0 +1,23 @@
+Temporal TypeScript SDK
+
+MIT License
+
+Copyright (c) 2021 Temporal Technologies Inc. All Rights Reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# `@temporalio/cloud`
+
+[![NPM](https://img.shields.io/npm/v/@temporalio/cloud?style=for-the-badge)](https://www.npmjs.com/package/@temporalio/cloud)
+
+Part of [Temporal](https://temporal.io)'s [TypeScript SDK](https://docs.temporal.io/typescript/introduction/).
+
+- [API reference](https://typescript.temporal.io/api/namespaces/cloud)
+- [Sample projects](https://github.com/temporalio/samples-typescript)

package/lib/cloud-operations-client.d.ts

@@ -0,0 +1,335 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { AsyncLocalStorage } from 'node:async_hooks';
+import * as grpc from '@grpc/grpc-js';
+import type { RPCImpl } from 'protobufjs';
+import { TLSConfig } from '@temporalio/common/lib/internal-non-workflow';
+import { Duration } from '@temporalio/common/lib/time';
+import { CallContext, HealthService, Metadata } from '@temporalio/client';
+import { CloudService } from './types';
+/**
+ * @experimental
+ */
+export interface CloudOperationsClientOptions {
+    /**
+     * Connection to use to communicate with the server.
+     */
+    connection: CloudOperationsConnection;
+    /**
+     * Version header for safer mutations.
+     * May or may not be required depending on cloud settings.
+     */
+    apiVersion?: string;
+}
+/**
+ * High level client for the Temporal Cloud API.
+ *
+ * @experimental
+ */
+export declare class CloudOperationsClient {
+    /**
+     * The underlying {@link CloudOperationsConnection | connection} used by this client.
+     *
+     * Clients are cheap to create, but connections are expensive. Where that make sense,
+     * a single connection may and should be reused by multiple `CloudOperationsClient`.
+     */
+    readonly connection: CloudOperationsConnection;
+    readonly options: Readonly<CloudOperationsClientOptions>;
+    constructor(options: CloudOperationsClientOptions);
+    /**
+     * Set a deadline for any service requests executed in `fn`'s scope.
+     *
+     * The deadline is a point in time after which any pending gRPC request will be considered as failed;
+     * this will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
+     * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+     *
+     * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
+     * possible for the client to end up waiting forever for a response.
+     *
+     * This method is only a convenience wrapper around {@link CloudOperationsConnection.withDeadline}.
+     *
+     * @param deadline a point in time after which the request will be considered as failed; either a
+     *                 Date object, or a number of milliseconds since the Unix epoch (UTC).
+     * @returns the value returned from `fn`
+     *
+     * @see https://grpc.io/docs/guides/deadlines/
+     */
+    withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
+    /**
+     * Set an {@link AbortSignal} that, when aborted, cancels any ongoing service requests executed in
+     * `fn`'s scope. This will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
+     * with code {@link grpc.status.CANCELLED|CANCELLED}.
+     *
+     * This method is only a convenience wrapper around {@link CloudOperationsConnection.withAbortSignal}.
+     *
+     * @example
+     *
+     * ```ts
+     * const ctrl = new AbortController();
+     * setTimeout(() => ctrl.abort(), 10_000);
+     * // 👇 throws if incomplete by the timeout.
+     * await conn.withAbortSignal(ctrl.signal, () => client.cloudService.getNamespace({ namespace }));
+     * ```
+     *
+     * @returns value returned from `fn`
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+     */
+    withAbortSignal<R>(abortSignal: AbortSignal, fn: () => Promise<R>): Promise<R>;
+    /**
+     * Set metadata for any service requests executed in `fn`'s scope.
+     *
+     * @returns returned value of `fn`
+     *
+     * This method is only a convenience wrapper around {@link CloudOperationsConnection.withMetadata}.
+     */
+    withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
+    /**
+     * Raw gRPC access to the Temporal Cloud Operations service.
+     *
+     * **NOTE**: The Temporal Cloud Operations service API Version provided in {@link options} is
+     * **not** automatically set on requests made via the raw gRPC service object. If the namespace
+     * requires it, you may need to do the following:
+     *
+     * ```
+     * const metadata: Metadata = { ['temporal-cloud-api-version']: apiVersion }
+     * const response = await client.withMetadata(metadata, async () => {
+     *   return client.cloudService.getNamespace({ namespace });
+     * });
+     * ```
+     */
+    get cloudService(): CloudService;
+}
+/**
+ * @experimental
+ */
+export interface CloudOperationsConnectionOptions {
+    /**
+     * The address of the Temporal Cloud Operations API to connect to, in `hostname:port` format.
+     *
+     * @default saas-api.tmprl.cloud:443
+     */
+    address?: string;
+    /**
+     * TLS configuration. TLS is required for connecting to the Temporal Cloud Operations API.
+     *
+     @default true
+     */
+    tls?: Pick<TLSConfig, 'serverNameOverride'> | true;
+    /**
+     * GRPC Channel arguments
+     *
+     * @see option descriptions {@link https://grpc.github.io/grpc/core/group__grpc__arg__keys.html | here}
+     *
+     * By default the SDK sets the following keepalive arguments:
+     *
+     * ```
+     * grpc.keepalive_permit_without_calls: 1
+     * grpc.keepalive_time_ms: 30_000
+     * grpc.keepalive_timeout_ms: 15_000
+     * ```
+     *
+     * To opt-out of keepalive, override these keys with `undefined`.
+     */
+    channelArgs?: grpc.ChannelOptions;
+    /**
+     * {@link https://grpc.github.io/grpc/node/module-src_client_interceptors.html | gRPC interceptors}
+     * which will be applied to every RPC call performed by this connection. By default, an interceptor
+     * will be included which automatically retries retryable errors. If you do not wish to perform
+     * automatic retries, set this to an empty list (or a list with your own interceptors). If you want
+     * to add your own interceptors while keeping the default retry behavior, add this to your list of
+     * interceptors: `makeGrpcRetryInterceptor(defaultGrpcRetryOptions())`.
+     *
+     * See:
+     * - {@link makeGrpcRetryInterceptor}
+     * - {@link defaultGrpcRetryOptions}
+     */
+    interceptors?: grpc.Interceptor[];
+    /**
+     * Optional mapping of gRPC metadata (HTTP headers) to send with each request to the server. An
+     * `Authorization` header set through `metadata` will be ignored and overriden by the value of the
+     * {@link apiKey} option.
+     *
+     * In order to dynamically set metadata, use {@link CloudOperationsConnection.withMetadata}
+     */
+    metadata?: Metadata;
+    /**
+     * API key for Temporal. This becomes the "Authorization" HTTP header with "Bearer " prepended.
+     *
+     * You may provide a static string or a callback. Also see {@link CloudOperationsConnection.withApiKey}
+     * or {@link Connection.setApiKey}
+     */
+    apiKey: string | (() => string);
+    /**
+     * Milliseconds to wait until establishing a connection with the server.
+     *
+     * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     * @default 10 seconds
+     */
+    connectTimeout?: Duration;
+}
+export type ResolvedCloudOperationsConnectionOptions = Required<Omit<CloudOperationsConnectionOptions, 'tls' | 'connectTimeout'>> & {
+    connectTimeoutMs: number;
+    credentials: grpc.ChannelCredentials;
+};
+interface RPCImplOptions {
+    serviceName: string;
+    client: grpc.Client;
+    callContextStorage: AsyncLocalStorage<CallContext>;
+    interceptors?: grpc.Interceptor[];
+    staticMetadata: Metadata;
+    apiKeyFnRef: {
+        fn?: () => string;
+    };
+}
+interface CloudOperationsConnectionCtorOptions {
+    readonly options: ResolvedCloudOperationsConnectionOptions;
+    readonly client: grpc.Client;
+    /**
+     * Raw gRPC access to the
+     * {@link https://github.com/temporalio/api-cloud/blob/main/temporal/api/cloud/cloudservice/v1/service.proto | Temporal Cloud's Operator Service}.
+     */
+    readonly cloudService: CloudService;
+    /**
+     * Raw gRPC access to the standard gRPC {@link https://github.com/grpc/grpc/blob/92f58c18a8da2728f571138c37760a721c8915a2/doc/health-checking.md | health service}.
+     */
+    readonly healthService: HealthService;
+    readonly callContextStorage: AsyncLocalStorage<CallContext>;
+    readonly apiKeyFnRef: {
+        fn?: () => string;
+    };
+}
+/**
+ * Client connection to the Temporal Cloud Operations Service endpoint.
+ *
+ * ⚠️ Connections are expensive to construct and should be reused.
+ * Make sure to {@link close} any unused connections to avoid leaking resources.
+ *
+ * @experimental
+ */
+export declare class CloudOperationsConnection {
+    private static readonly Client;
+    readonly options: ResolvedCloudOperationsConnectionOptions;
+    private readonly client;
+    /**
+     * Used to ensure `ensureConnected` is called once.
+     */
+    private connectPromise?;
+    /**
+     * Raw gRPC access to the
+     * {@link https://github.com/temporalio/api-cloud/blob/main/temporal/api/cloud/cloudservice/v1/service.proto | Temporal Cloud's Operator Service}.
+     *
+     * The Temporal Cloud Operator Service API defines how Temporal SDKs and other clients interact
+     * with the Temporal Cloud platform to perform administrative functions like registering a search
+     * attribute or a namespace.
+     *
+     * This Service API is NOT compatible with self-hosted Temporal deployments.
+     */
+    readonly cloudService: CloudService;
+    /**
+     * Raw gRPC access to the standard gRPC {@link https://github.com/grpc/grpc/blob/92f58c18a8da2728f571138c37760a721c8915a2/doc/health-checking.md | health service}.
+     */
+    readonly healthService: HealthService;
+    private readonly callContextStorage;
+    private readonly apiKeyFnRef;
+    protected static createCtorOptions(options: CloudOperationsConnectionOptions): CloudOperationsConnectionCtorOptions;
+    /**
+     * Create a lazy `CloudOperationsConnection` instance.
+     *
+     * This method does not verify connectivity with the server. We recommend using {@link connect} instead.
+     */
+    static lazy(options: CloudOperationsConnectionOptions): CloudOperationsConnection;
+    /**
+     * Establish a connection with the server and return a `CloudOperationsConnection` instance.
+     *
+     * This is the preferred method of creating connections as it verifies connectivity.
+     */
+    static connect(options: CloudOperationsConnectionOptions): Promise<CloudOperationsConnection>;
+    protected constructor({ options, client, cloudService, healthService, callContextStorage, apiKeyFnRef, }: CloudOperationsConnectionCtorOptions);
+    protected static generateRPCImplementation({ serviceName, client, callContextStorage, interceptors, staticMetadata, apiKeyFnRef, }: RPCImplOptions): RPCImpl;
+    /**
+     * Ensure connection can be established.
+     */
+    private ensureConnected;
+    /**
+     * Set a deadline for any service requests executed in `fn`'s scope.
+     *
+     * The deadline is a point in time after which any pending gRPC request will be considered as failed;
+     * this will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
+     * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+     *
+     * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
+     * possible for the client to end up waiting forever for a response.
+     *
+     * @param deadline a point in time after which the request will be considered as failed; either a
+     *                 Date object, or a number of milliseconds since the Unix epoch (UTC).
+     * @returns the value returned from `fn`
+     *
+     * @see https://grpc.io/docs/guides/deadlines/
+     */
+    withDeadline<ReturnType>(deadline: number | Date, fn: () => Promise<ReturnType>): Promise<ReturnType>;
+    /**
+     * Set an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} that, when aborted,
+     * cancels any ongoing requests executed in `fn`'s scope.
+     *
+     * @returns value returned from `fn`
+     *
+     * @example
+     *
+     * ```ts
+     * const ctrl = new AbortController();
+     * setTimeout(() => ctrl.abort(), 10_000);
+     * // 👇 throws if incomplete by the timeout.
+     * await conn.withAbortSignal(ctrl.signal, () => client.cloudService.someOperation(...));
+     * ```
+     */
+    withAbortSignal<ReturnType>(abortSignal: AbortSignal, fn: () => Promise<ReturnType>): Promise<ReturnType>;
+    /**
+     * Set metadata for any service requests executed in `fn`'s scope.
+     *
+     * The provided metadata is merged on top of any existing metadata in current scope.
+     *
+     * @returns value returned from `fn`
+     *
+     * @example
+     *
+     * ```ts
+     * const result = await conn.withMetadata({ someMetadata: 'value' }, () =>
+     *   conn.withMetadata({ otherKey: 'set' }, () => client.cloudService.someOperation(...)))
+     * );
+     * ```
+     */
+    withMetadata<ReturnType>(metadata: Metadata, fn: () => Promise<ReturnType>): Promise<ReturnType>;
+    /**
+     * Set the apiKey for any service requests executed in `fn`'s scope (thus changing the `Authorization` header).
+     *
+     * @returns value returned from `fn`
+     *
+     * @example
+     *
+     * ```ts
+     * const workflowHandle = await conn.withApiKey('secret', () =>
+     *   conn.withMetadata({ otherKey: 'set' }, () => client.start(options)))
+     * );
+     * ```
+     */
+    withApiKey<ReturnType>(apiKey: string, fn: () => Promise<ReturnType>): Promise<ReturnType>;
+    /**
+     * Set the {@link ConnectionOptions.apiKey} for all subsequent requests.
+     * A static string or a callback function may be provided.
+     */
+    setApiKey(apiKey: string | (() => string)): void;
+    /**
+     * Wait for successful connection to the server.
+     *
+     * @see https://grpc.github.io/grpc/node/grpc.Client.html#waitForReady__anchor
+     */
+    protected untilReady(deadline: number): Promise<void>;
+    /**
+     * Close the underlying gRPC client.
+     *
+     * Make sure to call this method to ensure proper resource cleanup.
+     */
+    close(): void;
+}
+export {};