telnyx 7.8.0 → 7.9.0

package/resources/storage/cloudfs/cloudfs.d.mts

@@ -0,0 +1,345 @@
+import { APIResource } from "../../../core/resource.mjs";
+import * as CloudfsAPI from "./cloudfs.mjs";
+import * as ActionsAPI from "./actions.mjs";
+import { ActionRotateMetaTokenParams, Actions } from "./actions.mjs";
+import { APIPromise } from "../../../core/api-promise.mjs";
+import { RequestOptions } from "../../../internal/request-options.mjs";
+/**
+ * Manage CloudFS filesystems — JuiceFS-compatible filesystems backed by Telnyx Cloud Storage
+ */
+export declare class Cloudfs extends APIResource {
+    actions: ActionsAPI.Actions;
+    /**
+     * Lists the CloudFS filesystems for the authenticated user's organization. Results
+     * use cursor-based pagination: fetch the next page by passing `meta.cursors.after`
+     * as `page[after]`, or follow the `meta.next` URL.
+     *
+     * @example
+     * ```ts
+     * const cloudfs = await client.storage.cloudfs.list();
+     * ```
+     */
+    list(query?: CloudfListParams | null | undefined, options?: RequestOptions): APIPromise<CloudfListResponse>;
+    /**
+     * Creates a CloudFS filesystem. Provisioning is synchronous — typically a few
+     * seconds, up to a few minutes — and the filesystem is returned with status
+     * `ready`, together with its S3 bucket and metadata connection details. This
+     * response is the only time the filesystem's `meta_token` — and the
+     * credential-bearing `meta_url` — are returned; store them securely. If the token
+     * is lost, issue a new one with the rotate-meta-token action. Names are unique
+     * within your organization: creating with an existing name returns a `422`.
+     * Requests are idempotent: retrying with the same `Idempotency-Key` within 24
+     * hours replays the original response instead of creating another filesystem.
+     *
+     * @example
+     * ```ts
+     * const cloudfsFilesystemResponseWrapper =
+     *   await client.storage.cloudfs.create({
+     *     name: 'agent-fs',
+     *     region: 'us-east-1',
+     *     'Idempotency-Key': 'Idempotency-Key',
+     *   });
+     * ```
+     */
+    create(params: CloudfCreateParams, options?: RequestOptions): APIPromise<CloudfsFilesystemResponseWrapper>;
+    /**
+     * Permanently deletes a CloudFS filesystem, removing its S3 bucket and its
+     * metadata database. Deletion is synchronous: the response returns the
+     * filesystem's final state with status `deleted`. There is no restore. A
+     * filesystem that is still `provisioning` returns a `409`. If the filesystem still
+     * contains data, the request may be rejected with a `409` — drain the bucket and
+     * retry.
+     *
+     * @example
+     * ```ts
+     * const cloudfsFilesystemDetailResponseWrapper =
+     *   await client.storage.cloudfs.delete(
+     *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   );
+     * ```
+     */
+    delete(id: string, options?: RequestOptions): APIPromise<CloudfsFilesystemDetailResponseWrapper>;
+    /**
+     * Retrieves a CloudFS filesystem by its ID. The returned `meta_url` omits the
+     * credential — the metadata token is only ever returned by create and
+     * rotate-meta-token. A filesystem whose last lifecycle action failed includes a
+     * customer-safe `error` message.
+     *
+     * @example
+     * ```ts
+     * const cloudfsFilesystemDetailResponseWrapper =
+     *   await client.storage.cloudfs.retrieve(
+     *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   );
+     * ```
+     */
+    retrieve(id: string, options?: RequestOptions): APIPromise<CloudfsFilesystemDetailResponseWrapper>;
+    /**
+     * Updates a CloudFS filesystem. Only `name` can be changed; other fields are
+     * immutable and unknown fields are rejected with a `400`. Renaming to a name that
+     * already exists in your organization returns a `422`.
+     *
+     * @example
+     * ```ts
+     * const cloudfsFilesystemDetailResponseWrapper =
+     *   await client.storage.cloudfs.update(
+     *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+     *   );
+     * ```
+     */
+    update(id: string, body: CloudfUpdateParams, options?: RequestOptions): APIPromise<CloudfsFilesystemDetailResponseWrapper>;
+}
+export interface CloudfsFilesystemDetailResponseWrapper {
+    /**
+     * A CloudFS filesystem as returned by get, update, and delete. `meta_url` omits
+     * the credential and there is no `meta_token` field — the token is only returned
+     * by create and rotate-meta-token.
+     */
+    data?: CloudfsFilesystemDetailResponseWrapper.Data;
+}
+export declare namespace CloudfsFilesystemDetailResponseWrapper {
+    /**
+     * A CloudFS filesystem as returned by get, update, and delete. `meta_url` omits
+     * the credential and there is no `meta_token` field — the token is only returned
+     * by create and rotate-meta-token.
+     */
+    interface Data {
+        id?: string;
+        created_at?: string;
+        /**
+         * Explanation of the most recent failed lifecycle action. Present only when the
+         * filesystem is in a `failed` state.
+         */
+        error?: string;
+        /**
+         * PostgreSQL connection URL for the filesystem's metadata database, without the
+         * credential. Combine it with your stored metadata token, or issue a new token
+         * with rotate-meta-token.
+         */
+        meta_url?: string;
+        name?: string;
+        record_type?: string;
+        region?: string;
+        /**
+         * Name of the bucket that stores this filesystem's data. Created during
+         * provisioning.
+         */
+        s3_bucket?: string;
+        /**
+         * URL of the Telnyx Cloud Storage endpoint backing this filesystem.
+         */
+        s3_endpoint?: string;
+        /**
+         * Lifecycle status of the filesystem. `ready` means it is fully provisioned and
+         * usable. `needs_format` means the storage bucket and metadata database were
+         * provisioned but the filesystem has not yet been formatted — run `juicefs format`
+         * with the filesystem's `meta_url` before mounting. `failed` means the last
+         * lifecycle action failed — see the filesystem's `error` message. `deleted`
+         * appears only in the delete response: deleted filesystems are excluded from list
+         * results and return a `404` on retrieval.
+         */
+        status?: CloudfsAPI.CloudfsFilesystemStatus;
+        updated_at?: string;
+    }
+}
+export interface CloudfsFilesystemResponseWrapper {
+    /**
+     * A CloudFS filesystem, including its metadata credential. This shape is returned
+     * only by create and rotate-meta-token.
+     */
+    data?: CloudfsFilesystemResponseWrapper.Data;
+}
+export declare namespace CloudfsFilesystemResponseWrapper {
+    /**
+     * A CloudFS filesystem, including its metadata credential. This shape is returned
+     * only by create and rotate-meta-token.
+     */
+    interface Data {
+        id?: string;
+        created_at?: string;
+        /**
+         * Metadata access token, in cleartext. Returned only by create and
+         * rotate-meta-token and not retrievable afterwards — store it securely.
+         */
+        meta_token?: string;
+        /**
+         * PostgreSQL connection URL for the filesystem's metadata database. In create and
+         * rotate-meta-token responses it embeds the metadata token as the password:
+         * `postgres://<database>:<meta_token>@us-east-1.telnyxcloudfs.com:5432/<database>?sslmode=require`
+         * (the example below is shown without the credential; the actual response includes
+         * it). Pass it to `juicefs mount`: the storage configuration is baked in at
+         * provisioning, so the metadata URL is all a client needs to mount the filesystem.
+         */
+        meta_url?: string;
+        name?: string;
+        record_type?: string;
+        region?: string;
+        /**
+         * Name of the bucket that stores this filesystem's data. Created during
+         * provisioning.
+         */
+        s3_bucket?: string;
+        /**
+         * URL of the Telnyx Cloud Storage endpoint backing this filesystem.
+         */
+        s3_endpoint?: string;
+        /**
+         * Lifecycle status of the filesystem. `ready` means it is fully provisioned and
+         * usable. `needs_format` means the storage bucket and metadata database were
+         * provisioned but the filesystem has not yet been formatted — run `juicefs format`
+         * with the filesystem's `meta_url` before mounting. `failed` means the last
+         * lifecycle action failed — see the filesystem's `error` message. `deleted`
+         * appears only in the delete response: deleted filesystems are excluded from list
+         * results and return a `404` on retrieval.
+         */
+        status?: CloudfsAPI.CloudfsFilesystemStatus;
+        updated_at?: string;
+    }
+}
+/**
+ * Lifecycle status of the filesystem. `ready` means it is fully provisioned and
+ * usable. `needs_format` means the storage bucket and metadata database were
+ * provisioned but the filesystem has not yet been formatted — run `juicefs format`
+ * with the filesystem's `meta_url` before mounting. `failed` means the last
+ * lifecycle action failed — see the filesystem's `error` message. `deleted`
+ * appears only in the delete response: deleted filesystems are excluded from list
+ * results and return a `404` on retrieval.
+ */
+export type CloudfsFilesystemStatus = 'provisioning' | 'ready' | 'needs_format' | 'deleting' | 'failed' | 'deleted';
+export interface CloudfListResponse {
+    data?: Array<CloudfListResponse.Data>;
+    meta?: CloudfListResponse.Meta;
+}
+export declare namespace CloudfListResponse {
+    /**
+     * A CloudFS filesystem as returned in list results. Connection details
+     * (`meta_url`, `meta_token`) are omitted — retrieve the filesystem by ID for its
+     * redacted `meta_url`.
+     */
+    interface Data {
+        id?: string;
+        created_at?: string;
+        name?: string;
+        record_type?: string;
+        region?: string;
+        /**
+         * Name of the bucket that stores this filesystem's data. Created during
+         * provisioning.
+         */
+        s3_bucket?: string;
+        /**
+         * URL of the Telnyx Cloud Storage endpoint backing this filesystem.
+         */
+        s3_endpoint?: string;
+        /**
+         * Lifecycle status of the filesystem. `ready` means it is fully provisioned and
+         * usable. `needs_format` means the storage bucket and metadata database were
+         * provisioned but the filesystem has not yet been formatted — run `juicefs format`
+         * with the filesystem's `meta_url` before mounting. `failed` means the last
+         * lifecycle action failed — see the filesystem's `error` message. `deleted`
+         * appears only in the delete response: deleted filesystems are excluded from list
+         * results and return a `404` on retrieval.
+         */
+        status?: CloudfsAPI.CloudfsFilesystemStatus;
+        updated_at?: string;
+    }
+    interface Meta {
+        /**
+         * Opaque cursors for the adjacent pages. Empty when there are no adjacent pages.
+         */
+        cursors?: Meta.Cursors;
+        /**
+         * Relative URL (path and query) of the next page. Omitted when there are no
+         * further results.
+         */
+        next?: string;
+        /**
+         * Relative URL (path and query) of the previous page. Omitted on the first page.
+         */
+        previous?: string;
+    }
+    namespace Meta {
+        /**
+         * Opaque cursors for the adjacent pages. Empty when there are no adjacent pages.
+         */
+        interface Cursors {
+            /**
+             * Cursor for the next page; pass it as `page[after]`. Omitted on the last page.
+             */
+            after?: string;
+            /**
+             * Cursor for the previous page; pass it as `page[before]`. Omitted on the first
+             * page.
+             */
+            before?: string;
+        }
+    }
+}
+export interface CloudfListParams {
+    /**
+     * Return only the filesystem whose name matches exactly.
+     */
+    'filter[name]'?: string;
+    /**
+     * Return only filesystems in this region.
+     */
+    'filter[region]'?: string;
+    /**
+     * Return only filesystems with this status. Unrecognized values are ignored.
+     */
+    'filter[status]'?: 'provisioning' | 'ready' | 'needs_format' | 'deleting' | 'failed';
+    /**
+     * Opaque cursor from a previous response's `meta.cursors.after`; returns the page
+     * after it. Mutually exclusive with `page[before]`.
+     */
+    'page[after]'?: string;
+    /**
+     * Opaque cursor from a previous response's `meta.cursors.before`; returns the page
+     * before it. Mutually exclusive with `page[after]`.
+     */
+    'page[before]'?: string;
+    /**
+     * The number of filesystems to return per page. Values above 250 are treated
+     * as 250.
+     */
+    'page[limit]'?: number;
+    /**
+     * Sort order for the results: a field name for ascending, or the field name
+     * prefixed with `-` for descending.
+     */
+    sort?: 'created_at' | '-created_at' | 'updated_at' | '-updated_at' | 'name' | '-name';
+}
+export interface CloudfCreateParams {
+    /**
+     * Body param: Filesystem name, unique within your organization. Names are trimmed
+     * and lowercased; after normalization they may contain lowercase letters, numbers,
+     * `.`, `_`, and `-` only.
+     */
+    name: string;
+    /**
+     * Body param: Region where the filesystem's storage and metadata are provisioned.
+     */
+    region: 'us-central-1' | 'us-east-1' | 'us-west-1';
+    /**
+     * Header param: Unique key that makes the request idempotent (1-255 characters:
+     * letters, numbers, `_`, and `-`). Retrying with the same key within 24 hours
+     * replays the original response (marked with an `Idempotent-Replayed: true`
+     * header) instead of repeating the action. Reusing a key with a different request
+     * returns a `422`; sending a key while the original request is still being
+     * processed returns a `409`.
+     */
+    'Idempotency-Key': string;
+}
+export interface CloudfUpdateParams {
+    /**
+     * New filesystem name, unique within your organization. Names are trimmed and
+     * lowercased; after normalization they may contain lowercase letters, numbers,
+     * `.`, `_`, and `-` only.
+     */
+    name?: string;
+}
+export declare namespace Cloudfs {
+    export { type CloudfsFilesystemDetailResponseWrapper as CloudfsFilesystemDetailResponseWrapper, type CloudfsFilesystemResponseWrapper as CloudfsFilesystemResponseWrapper, type CloudfsFilesystemStatus as CloudfsFilesystemStatus, type CloudfListResponse as CloudfListResponse, type CloudfListParams as CloudfListParams, type CloudfCreateParams as CloudfCreateParams, type CloudfUpdateParams as CloudfUpdateParams, };
+    export { Actions as Actions, type ActionRotateMetaTokenParams as ActionRotateMetaTokenParams };
+}
+//# sourceMappingURL=cloudfs.d.mts.map

package/resources/storage/cloudfs/cloudfs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudfs.d.mts","sourceRoot":"","sources":["../../../src/resources/storage/cloudfs/cloudfs.ts"],"names":[],"mappings":"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"}