cloudflare/src/resources/stream/watermarks.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 { PagePromise, SinglePage } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { maybeMultipartFormRequestOptions } from '../../internal/uploads';
import { path } from '../../internal/utils/path';

export class BaseWatermarks extends APIResource {
  static override readonly _key: readonly ['stream', 'watermarks'] = Object.freeze([
    'stream',
    'watermarks',
  ] as const);

  /**
   * Creates watermark profiles using a single `HTTP POST multipart/form-data`
   * request.
   *
   * @example
   * ```ts
   * const watermark = await client.stream.watermarks.create({
   *   account_id: '023e105f4ecef8ad9ca31a8372d0c353',
   * });
   * ```
   */
  create(params: WatermarkCreateParams, options?: RequestOptions): APIPromise<Watermark> {
    const { account_id, ...body } = params;
    return (
      this._client.post(
        path`/accounts/${account_id}/stream/watermarks`,
        maybeMultipartFormRequestOptions({ body, ...options }, this._client),
      ) as APIPromise<{ result: Watermark }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * Lists all watermark profiles for an account.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const watermark of client.stream.watermarks.list(
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * )) {
   *   // ...
   * }
   * ```
   */
  list(params: WatermarkListParams, options?: RequestOptions): PagePromise<WatermarksSinglePage, Watermark> {
    const { account_id } = params;
    return this._client.getAPIList(
      path`/accounts/${account_id}/stream/watermarks`,
      SinglePage<Watermark>,
      options,
    );
  }

  /**
   * Deletes a watermark profile.
   *
   * @example
   * ```ts
   * const watermark = await client.stream.watermarks.delete(
   *   'ea95132c15732412d22c1476fa83f27a',
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * );
   * ```
   */
  delete(
    identifier: string,
    params: WatermarkDeleteParams,
    options?: RequestOptions,
  ): APIPromise<WatermarkDeleteResponse> {
    const { account_id } = params;
    return (
      this._client.delete(
        path`/accounts/${account_id}/stream/watermarks/${identifier}`,
        options,
      ) as APIPromise<{ result: WatermarkDeleteResponse }>
    )._thenUnwrap((obj) => obj.result);
  }

  /**
   * Retrieves details for a single watermark profile.
   *
   * @example
   * ```ts
   * const watermark = await client.stream.watermarks.get(
   *   'ea95132c15732412d22c1476fa83f27a',
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * );
   * ```
   */
  get(identifier: string, params: WatermarkGetParams, options?: RequestOptions): APIPromise<Watermark> {
    const { account_id } = params;
    return (
      this._client.get(path`/accounts/${account_id}/stream/watermarks/${identifier}`, options) as APIPromise<{
        result: Watermark;
      }>
    )._thenUnwrap((obj) => obj.result);
  }
}
export class Watermarks extends BaseWatermarks {}

export type WatermarksSinglePage = SinglePage<Watermark>;

export interface Watermark {
  /**
   * The date and a time a watermark profile was created.
   */
  created?: string;

  /**
   * The source URL for a downloaded image. If the watermark profile was created via
   * direct upload, this field is null.
   */
  downloadedFrom?: string;

  /**
   * The height of the image in pixels.
   */
  height?: number;

  /**
   * A short description of the watermark profile.
   */
  name?: string;

  /**
   * The translucency of the image. A value of `0.0` makes the image completely
   * transparent, and `1.0` makes the image completely opaque. Note that if the image
   * is already semi-transparent, setting this to `1.0` will not make the image
   * completely opaque.
   */
  opacity?: number;

  /**
   * The whitespace between the adjacent edges (determined by position) of the video
   * and the image. `0.0` indicates no padding, and `1.0` indicates a fully padded
   * video width or length, as determined by the algorithm.
   */
  padding?: number;

  /**
   * The location of the image. Valid positions are: `upperRight`, `upperLeft`,
   * `lowerLeft`, `lowerRight`, and `center`. Note that `center` ignores the
   * `padding` parameter.
   */
  position?: string;

  /**
   * The size of the image relative to the overall size of the video. This parameter
   * will adapt to horizontal and vertical videos automatically. `0.0` indicates no
   * scaling (use the size of the image as-is), and `1.0 `fills the entire video.
   */
  scale?: number;

  /**
   * The size of the image in bytes.
   */
  size?: number;

  /**
   * The unique identifier for a watermark profile.
   */
  uid?: string;

  /**
   * The width of the image in pixels.
   */
  width?: number;
}

export type WatermarkDeleteResponse = string;

export interface WatermarkCreateParams {
  /**
   * Path param: The account identifier tag.
   */
  account_id: string;

  /**
   * Body param: A short description of the watermark profile.
   */
  name?: string;

  /**
   * Body param: The translucency of the image. A value of `0.0` makes the image
   * completely transparent, and `1.0` makes the image completely opaque. Note that
   * if the image is already semi-transparent, setting this to `1.0` will not make
   * the image completely opaque.
   */
  opacity?: number;

  /**
   * Body param: The whitespace between the adjacent edges (determined by position)
   * of the video and the image. `0.0` indicates no padding, and `1.0` indicates a
   * fully padded video width or length, as determined by the algorithm.
   */
  padding?: number;

  /**
   * Body param: The location of the image. Valid positions are: `upperRight`,
   * `upperLeft`, `lowerLeft`, `lowerRight`, and `center`. Note that `center` ignores
   * the `padding` parameter.
   */
  position?: string;

  /**
   * Body param: The size of the image relative to the overall size of the video.
   * This parameter will adapt to horizontal and vertical videos automatically. `0.0`
   * indicates no scaling (use the size of the image as-is), and `1.0 `fills the
   * entire video.
   */
  scale?: number;

  /**
   * Body param: URL of the watermark image to copy.
   */
  url?: string;
}

export interface WatermarkListParams {
  /**
   * The account identifier tag.
   */
  account_id: string;
}

export interface WatermarkDeleteParams {
  /**
   * The account identifier tag.
   */
  account_id: string;
}

export interface WatermarkGetParams {
  /**
   * The account identifier tag.
   */
  account_id: string;
}

export declare namespace Watermarks {
  export {
    type Watermark as Watermark,
    type WatermarkDeleteResponse as WatermarkDeleteResponse,
    type WatermarksSinglePage as WatermarksSinglePage,
    type WatermarkCreateParams as WatermarkCreateParams,
    type WatermarkListParams as WatermarkListParams,
    type WatermarkDeleteParams as WatermarkDeleteParams,
    type WatermarkGetParams as WatermarkGetParams,
  };
}