gumnut-sdk 0.1.0

package/src/internal/utils/path.ts

@@ -0,0 +1,63 @@
+import { GumnutError } from '../../core/error';
+
+/**
+ * Percent-encode everything that isn't safe to have in a path without encoding safe chars.
+ *
+ * Taken from https://datatracker.ietf.org/doc/html/rfc3986#section-3.3:
+ * > unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
+ * > sub-delims  = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+ * > pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
+ */
+export function encodeURIPath(str: string) {
+  return str.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
+}
+
+export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
+  function path(statics: readonly string[], ...params: readonly unknown[]): string {
+    // If there are no params, no processing is needed.
+    if (statics.length === 1) return statics[0]!;
+
+    let postPath = false;
+    const path = statics.reduce((previousValue, currentValue, index) => {
+      if (/[?#]/.test(currentValue)) {
+        postPath = true;
+      }
+      return (
+        previousValue +
+        currentValue +
+        (index === params.length ? '' : (postPath ? encodeURIComponent : pathEncoder)(String(params[index])))
+      );
+    }, '');
+
+    const pathOnly = path.split(/[?#]/, 1)[0]!;
+    const invalidSegments = [];
+    const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
+    let match;
+
+    // Find all invalid segments
+    while ((match = invalidSegmentPattern.exec(pathOnly)) !== null) {
+      invalidSegments.push({
+        start: match.index,
+        length: match[0].length,
+      });
+    }
+
+    if (invalidSegments.length > 0) {
+      let lastEnd = 0;
+      const underline = invalidSegments.reduce((acc, segment) => {
+        const spaces = ' '.repeat(segment.start - lastEnd);
+        const arrows = '^'.repeat(segment.length);
+        lastEnd = segment.start + segment.length;
+        return acc + spaces + arrows;
+      }, '');
+
+      throw new GumnutError(`Path parameters result in path with invalid segments:\n${path}\n${underline}`);
+    }
+
+    return path;
+  };
+
+/**
+ * URI-encodes path params and ensures no unsafe /./ or /../ path segments are introduced.
+ */
+export const path = createPathTagFunction(encodeURIPath);

package/src/internal/utils/sleep.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

package/src/internal/utils/uuid.ts

@@ -0,0 +1,17 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+/**
+ * https://stackoverflow.com/a/2117523
+ */
+export let uuid4 = function () {
+  const { crypto } = globalThis as any;
+  if (crypto?.randomUUID) {
+    uuid4 = crypto.randomUUID.bind(crypto);
+    return crypto.randomUUID();
+  }
+  const u8 = new Uint8Array(1);
+  const randomByte = crypto ? () => crypto.getRandomValues(u8)[0]! : () => (Math.random() * 0xff) & 0xff;
+  return '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, (c) =>
+    (+c ^ (randomByte() & (15 >> (+c / 4)))).toString(16),
+  );
+};

package/src/internal/utils/values.ts

@@ -0,0 +1,102 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { GumnutError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new GumnutError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new GumnutError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new GumnutError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new GumnutError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new GumnutError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,8 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/albums/albums.ts

@@ -0,0 +1,110 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as AssetsAPI from './assets';
+import {
+  AlbumAssetAssociation,
+  AssetAddParams,
+  AssetListResponse,
+  AssetRemoveParams,
+  Assets,
+} from './assets';
+import { APIPromise } from '../../core/api-promise';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Albums extends APIResource {
+  assets: AssetsAPI.Assets = new AssetsAPI.Assets(this._client);
+
+  /**
+   * Creates a new, empty album with a given name and optional description.
+   */
+  create(body: AlbumCreateParams, options?: RequestOptions): APIPromise<AlbumResponse> {
+    return this._client.post('/api/albums', { body, ...options });
+  }
+
+  /**
+   * Retrieves details for a specific album.
+   */
+  retrieve(albumID: string, options?: RequestOptions): APIPromise<AlbumResponse> {
+    return this._client.get(path`/api/albums/${albumID}`, options);
+  }
+
+  /**
+   * Updates the name and/or description of a specific album.
+   */
+  update(albumID: string, body: AlbumUpdateParams, options?: RequestOptions): APIPromise<AlbumResponse> {
+    return this._client.patch(path`/api/albums/${albumID}`, { body, ...options });
+  }
+
+  /**
+   * Retrieves a paginated list of albums, ordered by creation time, descending.
+   */
+  list(
+    query: AlbumListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AlbumResponsesCursorPage, AlbumResponse> {
+    return this._client.getAPIList('/api/albums', CursorPage<AlbumResponse>, { query, ...options });
+  }
+
+  /**
+   * Deletes a specific album. Note: This does not delete the assets within the
+   * album.
+   */
+  delete(albumID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/api/albums/${albumID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type AlbumResponsesCursorPage = CursorPage<AlbumResponse>;
+
+export interface AlbumResponse {
+  id: string;
+
+  created_at: string;
+
+  name: string;
+
+  updated_at: string;
+
+  description?: string | null;
+}
+
+export interface AlbumCreateParams {
+  name: string;
+
+  description?: string | null;
+}
+
+export interface AlbumUpdateParams {
+  description?: string | null;
+
+  name?: string | null;
+}
+
+export interface AlbumListParams extends CursorPageParams {}
+
+Albums.Assets = Assets;
+
+export declare namespace Albums {
+  export {
+    type AlbumResponse as AlbumResponse,
+    type AlbumResponsesCursorPage as AlbumResponsesCursorPage,
+    type AlbumCreateParams as AlbumCreateParams,
+    type AlbumUpdateParams as AlbumUpdateParams,
+    type AlbumListParams as AlbumListParams,
+  };
+
+  export {
+    Assets as Assets,
+    type AlbumAssetAssociation as AlbumAssetAssociation,
+    type AssetListResponse as AssetListResponse,
+    type AssetAddParams as AssetAddParams,
+    type AssetRemoveParams as AssetRemoveParams,
+  };
+}

package/src/resources/albums/assets.ts

@@ -0,0 +1,63 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as AssetsAPI from '../assets';
+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 Assets extends APIResource {
+  /**
+   * Retrieves a list of all assets contained within a specific album.
+   */
+  list(albumID: string, options?: RequestOptions): APIPromise<AssetListResponse> {
+    return this._client.get(path`/api/albums/${albumID}/assets`, options);
+  }
+
+  /**
+   * Adds one or more existing assets to a specific album.
+   */
+  add(albumID: string, body: AssetAddParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(path`/api/albums/${albumID}/assets`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Removes one or more assets from a specific album. Note: This does not delete the
+   * assets themselves.
+   */
+  remove(albumID: string, body: AssetRemoveParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/api/albums/${albumID}/assets`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface AlbumAssetAssociation {
+  asset_ids: Array<string>;
+}
+
+export type AssetListResponse = Array<AssetsAPI.AssetResponse>;
+
+export interface AssetAddParams {
+  asset_ids: Array<string>;
+}
+
+export interface AssetRemoveParams {
+  asset_ids: Array<string>;
+}
+
+export declare namespace Assets {
+  export {
+    type AlbumAssetAssociation as AlbumAssetAssociation,
+    type AssetListResponse as AssetListResponse,
+    type AssetAddParams as AssetAddParams,
+    type AssetRemoveParams as AssetRemoveParams,
+  };
+}

package/src/resources/albums/index.ts

@@ -0,0 +1,17 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Albums,
+  type AlbumResponse,
+  type AlbumCreateParams,
+  type AlbumUpdateParams,
+  type AlbumListParams,
+  type AlbumResponsesCursorPage,
+} from './albums';
+export {
+  Assets,
+  type AlbumAssetAssociation,
+  type AssetListResponse,
+  type AssetAddParams,
+  type AssetRemoveParams,
+} from './assets';

package/src/resources/albums.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './albums/index';

package/src/resources/api-keys.ts

@@ -0,0 +1,73 @@
+// 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 APIKeys extends APIResource {
+  /**
+   * Creates a new API key for the current user
+   */
+  create(options?: RequestOptions): APIPromise<APIKeyCreateResponse> {
+    return this._client.post('/api-keys/', options);
+  }
+
+  /**
+   * Retrieves a list of all API keys for the current user
+   */
+  list(options?: RequestOptions): APIPromise<APIKeyListResponse> {
+    return this._client.get('/api-keys/', options);
+  }
+
+  /**
+   * Deletes a specific API key
+   */
+  delete(keyID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/api-keys/${keyID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface APIKeyResponse {
+  id: string;
+
+  created_at: string;
+
+  is_active: boolean;
+
+  last_used_at: string | null;
+
+  name: string | null;
+}
+
+/**
+ * The only difference between this and APIKeyResponse is that it includes the full
+ * API key.
+ */
+export interface APIKeyCreateResponse {
+  id: string;
+
+  api_key: string;
+
+  created_at: string;
+
+  is_active: boolean;
+
+  last_used_at: string | null;
+
+  name: string | null;
+}
+
+export type APIKeyListResponse = Array<APIKeyResponse>;
+
+export declare namespace APIKeys {
+  export {
+    type APIKeyResponse as APIKeyResponse,
+    type APIKeyCreateResponse as APIKeyCreateResponse,
+    type APIKeyListResponse as APIKeyListResponse,
+  };
+}

package/src/resources/assets.ts

@@ -0,0 +1,207 @@
+// 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 { CursorPage, type CursorPageParams, PagePromise } from '../core/pagination';
+import { type Uploadable } from '../core/uploads';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { multipartFormRequestOptions } from '../internal/uploads';
+import { path } from '../internal/utils/path';
+
+export class Assets extends APIResource {
+  /**
+   * Uploads a new asset file (image or video) along with its metadata. If an asset
+   * with the same checksum already exists, returns the existing asset's metadata.
+   */
+  create(body: AssetCreateParams, options?: RequestOptions): APIPromise<AssetResponse> {
+    return this._client.post('/api/assets', multipartFormRequestOptions({ body, ...options }, this._client));
+  }
+
+  /**
+   * Retrieves detailed metadata for a specific asset, including EXIF information and
+   * asset metrics.
+   */
+  retrieve(assetID: string, options?: RequestOptions): APIPromise<AssetResponse> {
+    return this._client.get(path`/api/assets/${assetID}`, options);
+  }
+
+  /**
+   * Retrieves a paginated list of assets, optionally filtered by album. Assets are
+   * ordered by local creation time, descending.
+   */
+  list(
+    query: AssetListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AssetResponsesCursorPage, AssetResponse> {
+    return this._client.getAPIList('/api/assets', CursorPage<AssetResponse>, { query, ...options });
+  }
+
+  /**
+   * Deletes a specific asset and its associated data (including the file from
+   * storage).
+   */
+  delete(assetID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/api/assets/${assetID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Downloads the original file for a specific asset.
+   */
+  download(assetID: string, options?: RequestOptions): APIPromise<Response> {
+    return this._client.get(path`/api/assets/${assetID}/download`, {
+      ...options,
+      headers: buildHeaders([{ Accept: 'image/*' }, options?.headers]),
+      __binaryResponse: true,
+    });
+  }
+
+  /**
+   * Downloads a thumbnail for a specific asset. The exact thumbnail returned depends
+   * on availability and the optional `size` parameter.
+   */
+  downloadThumbnail(
+    assetID: string,
+    query: AssetDownloadThumbnailParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<Response> {
+    return this._client.get(path`/api/assets/${assetID}/thumbnail`, {
+      query,
+      ...options,
+      headers: buildHeaders([{ Accept: 'image/*' }, options?.headers]),
+      __binaryResponse: true,
+    });
+  }
+}
+
+export type AssetResponsesCursorPage = CursorPage<AssetResponse>;
+
+export interface AssetResponse {
+  id: string;
+
+  checksum: string;
+
+  created_at: string;
+
+  device_asset_id: string;
+
+  device_id: string;
+
+  file_created_at: string;
+
+  file_modified_at: string;
+
+  local_datetime: string;
+
+  mime_type: string;
+
+  original_file_name: string;
+
+  updated_at: string;
+
+  download_url?: string | null;
+
+  exif?: AssetResponse.Exif | null;
+
+  metrics?: Record<string, number | null> | null;
+
+  thumbnail_url?: string | null;
+}
+
+export namespace AssetResponse {
+  export interface Exif {
+    altitude?: number | null;
+
+    auto_stack_id?: string | null;
+
+    city?: string | null;
+
+    country?: string | null;
+
+    description?: string | null;
+
+    digitized_datetime?: string | null;
+
+    exposure_bias?: number | null;
+
+    exposure_time?: number | null;
+
+    f_number?: number | null;
+
+    focal_length?: number | null;
+
+    fps?: number | null;
+
+    iso?: number | null;
+
+    latitude?: number | null;
+
+    lens_model?: string | null;
+
+    live_photo_cid?: string | null;
+
+    longitude?: number | null;
+
+    make?: string | null;
+
+    model?: string | null;
+
+    modified_datetime?: string | null;
+
+    orientation?: number | null;
+
+    original_datetime?: string | null;
+
+    profile_description?: string | null;
+
+    projection_type?: string | null;
+
+    rating?: number | null;
+
+    state?: string | null;
+  }
+}
+
+export interface AssetCreateParams {
+  asset_data: Uploadable;
+
+  device_asset_id: string;
+
+  device_id: string;
+
+  file_created_at: string;
+
+  file_modified_at: string;
+}
+
+export interface AssetListParams extends CursorPageParams {
+  /**
+   * Filter by assets in a specific album
+   */
+  album_id?: string | null;
+
+  /**
+   * Filter by assets associated with a specific person ID
+   */
+  person_id?: string | null;
+}
+
+export interface AssetDownloadThumbnailParams {
+  /**
+   * Desired thumbnail size (e.g., thumbnail, preview)
+   */
+  size?: string | null;
+}
+
+export declare namespace Assets {
+  export {
+    type AssetResponse as AssetResponse,
+    type AssetResponsesCursorPage as AssetResponsesCursorPage,
+    type AssetCreateParams as AssetCreateParams,
+    type AssetListParams as AssetListParams,
+    type AssetDownloadThumbnailParams as AssetDownloadThumbnailParams,
+  };
+}