cloudflare/src/resources/r2/buckets/locks.ts

The official TypeScript library for the Cloudflare API

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../../core/resource';
import { APIPromise } from '../../../core/api-promise';
import { buildHeaders } from '../../../internal/headers';
import { RequestOptions } from '../../../internal/request-options';
import { path } from '../../../internal/utils/path';

export class BaseLocks extends APIResource {
  static override readonly _key: readonly ['r2', 'buckets', 'locks'] = Object.freeze([
    'r2',
    'buckets',
    'locks',
  ] as const);

  /**
   * Replaces the lock rules for an R2 bucket. Enabled rules prevent matching objects
   * from being overwritten or deleted for a duration, until a date, or indefinitely.
   * Rules apply to existing and newly uploaded objects.
   *
   * @example
   * ```ts
   * const lock = await client.r2.buckets.locks.update(
   *   'example-bucket',
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * );
   * ```
   */
  update(
    bucketName: string,
    params: LockUpdateParams,
    options?: RequestOptions,
  ): APIPromise<LockUpdateResponse> {
    const { account_id, 'cf-r2-jurisdiction': cfR2Jurisdiction, ...body } = params;
    return (
      this._client.put(path`/accounts/${account_id}/r2/buckets/${bucketName}/lock`, {
        body,
        ...options,
        headers: buildHeaders([
          {
            ...(cfR2Jurisdiction?.toString() != null ?
              { 'cf-r2-jurisdiction': cfR2Jurisdiction?.toString() }
            : undefined),
          },
          options?.headers,
        ]),
      }) as APIPromise<{ result: LockUpdateResponse }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * Get lock rules for a bucket.
   *
   * @example
   * ```ts
   * const lock = await client.r2.buckets.locks.get(
   *   'example-bucket',
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * );
   * ```
   */
  get(bucketName: string, params: LockGetParams, options?: RequestOptions): APIPromise<LockGetResponse> {
    const { account_id, 'cf-r2-jurisdiction': cfR2Jurisdiction } = params;
    return (
      this._client.get(path`/accounts/${account_id}/r2/buckets/${bucketName}/lock`, {
        ...options,
        headers: buildHeaders([
          {
            ...(cfR2Jurisdiction?.toString() != null ?
              { 'cf-r2-jurisdiction': cfR2Jurisdiction?.toString() }
            : undefined),
          },
          options?.headers,
        ]),
      }) as APIPromise<{ result: LockGetResponse }>
    )._thenUnwrap((obj) => obj.result);
  }
}
export class Locks extends BaseLocks {}

export type LockUpdateResponse = unknown;

export interface LockGetResponse {
  rules?: Array<LockGetResponse.Rule>;
}

export namespace LockGetResponse {
  export interface Rule {
    /**
     * Unique identifier for this rule.
     */
    id: string;

    /**
     * Condition to apply a lock rule to an object for how long in seconds.
     */
    condition:
      | Rule.R2LockRuleAgeCondition
      | Rule.R2LockRuleDateCondition
      | Rule.R2LockRuleIndefiniteCondition;

    /**
     * Whether or not this rule is in effect.
     */
    enabled: boolean;

    /**
     * Rule will only apply to objects/uploads in the bucket that start with the given
     * prefix, an empty prefix can be provided to scope rule to all objects/uploads.
     */
    prefix?: string;
  }

  export namespace Rule {
    /**
     * Condition to apply a lock rule to an object for how long in seconds.
     */
    export interface R2LockRuleAgeCondition {
      maxAgeSeconds: number;

      type: 'Age';
    }

    /**
     * Condition to apply a lock rule to an object until a specific date.
     */
    export interface R2LockRuleDateCondition {
      date: string;

      type: 'Date';
    }

    /**
     * Condition to apply a lock rule indefinitely.
     */
    export interface R2LockRuleIndefiniteCondition {
      type: 'Indefinite';
    }
  }
}

export interface LockUpdateParams {
  /**
   * Path param: Cloudflare account ID that owns the R2 resource.
   */
  account_id: string;

  /**
   * Body param
   */
  rules?: Array<LockUpdateParams.Rule>;

  /**
   * Header param: Jurisdiction where objects in this bucket are guaranteed to be
   * stored.
   */
  'cf-r2-jurisdiction'?: 'default' | 'eu' | 'us' | 'fedramp' | 'fedramp-high';
}

export namespace LockUpdateParams {
  export interface Rule {
    /**
     * Unique identifier for this rule.
     */
    id: string;

    /**
     * Condition to apply a lock rule to an object for how long in seconds.
     */
    condition:
      | Rule.R2LockRuleAgeCondition
      | Rule.R2LockRuleDateCondition
      | Rule.R2LockRuleIndefiniteCondition;

    /**
     * Whether or not this rule is in effect.
     */
    enabled: boolean;

    /**
     * Rule will only apply to objects/uploads in the bucket that start with the given
     * prefix, an empty prefix can be provided to scope rule to all objects/uploads.
     */
    prefix?: string;
  }

  export namespace Rule {
    /**
     * Condition to apply a lock rule to an object for how long in seconds.
     */
    export interface R2LockRuleAgeCondition {
      maxAgeSeconds: number;

      type: 'Age';
    }

    /**
     * Condition to apply a lock rule to an object until a specific date.
     */
    export interface R2LockRuleDateCondition {
      date: string;

      type: 'Date';
    }

    /**
     * Condition to apply a lock rule indefinitely.
     */
    export interface R2LockRuleIndefiniteCondition {
      type: 'Indefinite';
    }
  }
}

export interface LockGetParams {
  /**
   * Path param: Cloudflare account ID that owns the R2 resource.
   */
  account_id: string;

  /**
   * Header param: Jurisdiction where objects in this bucket are guaranteed to be
   * stored.
   */
  'cf-r2-jurisdiction'?: 'default' | 'eu' | 'us' | 'fedramp' | 'fedramp-high';
}

export declare namespace Locks {
  export {
    type LockUpdateResponse as LockUpdateResponse,
    type LockGetResponse as LockGetResponse,
    type LockUpdateParams as LockUpdateParams,
    type LockGetParams as LockGetParams,
  };
}