@valtown/sdk 1.1.0 → 1.3.0

package/src/internal/qs/utils.ts

@@ -0,0 +1,265 @@
+import { RFC1738 } from './formats';
+import type { DefaultEncoder, Format } from './types';
+
+const has = Object.prototype.hasOwnProperty;
+const is_array = Array.isArray;
+
+const hex_table = (() => {
+  const array = [];
+  for (let i = 0; i < 256; ++i) {
+    array.push('%' + ((i < 16 ? '0' : '') + i.toString(16)).toUpperCase());
+  }
+
+  return array;
+})();
+
+function compact_queue<T extends Record<string, any>>(queue: Array<{ obj: T; prop: string }>) {
+  while (queue.length > 1) {
+    const item = queue.pop();
+    if (!item) continue;
+
+    const obj = item.obj[item.prop];
+
+    if (is_array(obj)) {
+      const compacted: unknown[] = [];
+
+      for (let j = 0; j < obj.length; ++j) {
+        if (typeof obj[j] !== 'undefined') {
+          compacted.push(obj[j]);
+        }
+      }
+
+      // @ts-ignore
+      item.obj[item.prop] = compacted;
+    }
+  }
+}
+
+function array_to_object(source: any[], options: { plainObjects: boolean }) {
+  const obj = options && options.plainObjects ? Object.create(null) : {};
+  for (let i = 0; i < source.length; ++i) {
+    if (typeof source[i] !== 'undefined') {
+      obj[i] = source[i];
+    }
+  }
+
+  return obj;
+}
+
+export function merge(
+  target: any,
+  source: any,
+  options: { plainObjects?: boolean; allowPrototypes?: boolean } = {},
+) {
+  if (!source) {
+    return target;
+  }
+
+  if (typeof source !== 'object') {
+    if (is_array(target)) {
+      target.push(source);
+    } else if (target && typeof target === 'object') {
+      if (
+        (options && (options.plainObjects || options.allowPrototypes)) ||
+        !has.call(Object.prototype, source)
+      ) {
+        target[source] = true;
+      }
+    } else {
+      return [target, source];
+    }
+
+    return target;
+  }
+
+  if (!target || typeof target !== 'object') {
+    return [target].concat(source);
+  }
+
+  let mergeTarget = target;
+  if (is_array(target) && !is_array(source)) {
+    // @ts-ignore
+    mergeTarget = array_to_object(target, options);
+  }
+
+  if (is_array(target) && is_array(source)) {
+    source.forEach(function (item, i) {
+      if (has.call(target, i)) {
+        const targetItem = target[i];
+        if (targetItem && typeof targetItem === 'object' && item && typeof item === 'object') {
+          target[i] = merge(targetItem, item, options);
+        } else {
+          target.push(item);
+        }
+      } else {
+        target[i] = item;
+      }
+    });
+    return target;
+  }
+
+  return Object.keys(source).reduce(function (acc, key) {
+    const value = source[key];
+
+    if (has.call(acc, key)) {
+      acc[key] = merge(acc[key], value, options);
+    } else {
+      acc[key] = value;
+    }
+    return acc;
+  }, mergeTarget);
+}
+
+export function assign_single_source(target: any, source: any) {
+  return Object.keys(source).reduce(function (acc, key) {
+    acc[key] = source[key];
+    return acc;
+  }, target);
+}
+
+export function decode(str: string, _: any, charset: string) {
+  const strWithoutPlus = str.replace(/\+/g, ' ');
+  if (charset === 'iso-8859-1') {
+    // unescape never throws, no try...catch needed:
+    return strWithoutPlus.replace(/%[0-9a-f]{2}/gi, unescape);
+  }
+  // utf-8
+  try {
+    return decodeURIComponent(strWithoutPlus);
+  } catch (e) {
+    return strWithoutPlus;
+  }
+}
+
+const limit = 1024;
+
+export const encode: (
+  str: any,
+  defaultEncoder: DefaultEncoder,
+  charset: string,
+  type: 'key' | 'value',
+  format: Format,
+) => string = (str, _defaultEncoder, charset, _kind, format: Format) => {
+  // This code was originally written by Brian White for the io.js core querystring library.
+  // It has been adapted here for stricter adherence to RFC 3986
+  if (str.length === 0) {
+    return str;
+  }
+
+  let string = str;
+  if (typeof str === 'symbol') {
+    string = Symbol.prototype.toString.call(str);
+  } else if (typeof str !== 'string') {
+    string = String(str);
+  }
+
+  if (charset === 'iso-8859-1') {
+    return escape(string).replace(/%u[0-9a-f]{4}/gi, function ($0) {
+      return '%26%23' + parseInt($0.slice(2), 16) + '%3B';
+    });
+  }
+
+  let out = '';
+  for (let j = 0; j < string.length; j += limit) {
+    const segment = string.length >= limit ? string.slice(j, j + limit) : string;
+    const arr = [];
+
+    for (let i = 0; i < segment.length; ++i) {
+      let c = segment.charCodeAt(i);
+      if (
+        c === 0x2d || // -
+        c === 0x2e || // .
+        c === 0x5f || // _
+        c === 0x7e || // ~
+        (c >= 0x30 && c <= 0x39) || // 0-9
+        (c >= 0x41 && c <= 0x5a) || // a-z
+        (c >= 0x61 && c <= 0x7a) || // A-Z
+        (format === RFC1738 && (c === 0x28 || c === 0x29)) // ( )
+      ) {
+        arr[arr.length] = segment.charAt(i);
+        continue;
+      }
+
+      if (c < 0x80) {
+        arr[arr.length] = hex_table[c];
+        continue;
+      }
+
+      if (c < 0x800) {
+        arr[arr.length] = hex_table[0xc0 | (c >> 6)]! + hex_table[0x80 | (c & 0x3f)];
+        continue;
+      }
+
+      if (c < 0xd800 || c >= 0xe000) {
+        arr[arr.length] =
+          hex_table[0xe0 | (c >> 12)]! + hex_table[0x80 | ((c >> 6) & 0x3f)] + hex_table[0x80 | (c & 0x3f)];
+        continue;
+      }
+
+      i += 1;
+      c = 0x10000 + (((c & 0x3ff) << 10) | (segment.charCodeAt(i) & 0x3ff));
+
+      arr[arr.length] =
+        hex_table[0xf0 | (c >> 18)]! +
+        hex_table[0x80 | ((c >> 12) & 0x3f)] +
+        hex_table[0x80 | ((c >> 6) & 0x3f)] +
+        hex_table[0x80 | (c & 0x3f)];
+    }
+
+    out += arr.join('');
+  }
+
+  return out;
+};
+
+export function compact(value: any) {
+  const queue = [{ obj: { o: value }, prop: 'o' }];
+  const refs = [];
+
+  for (let i = 0; i < queue.length; ++i) {
+    const item = queue[i];
+    // @ts-ignore
+    const obj = item.obj[item.prop];
+
+    const keys = Object.keys(obj);
+    for (let j = 0; j < keys.length; ++j) {
+      const key = keys[j]!;
+      const val = obj[key];
+      if (typeof val === 'object' && val !== null && refs.indexOf(val) === -1) {
+        queue.push({ obj: obj, prop: key });
+        refs.push(val);
+      }
+    }
+  }
+
+  compact_queue(queue);
+
+  return value;
+}
+
+export function is_regexp(obj: any) {
+  return Object.prototype.toString.call(obj) === '[object RegExp]';
+}
+
+export function is_buffer(obj: any) {
+  if (!obj || typeof obj !== 'object') {
+    return false;
+  }
+
+  return !!(obj.constructor && obj.constructor.isBuffer && obj.constructor.isBuffer(obj));
+}
+
+export function combine(a: any, b: any) {
+  return [].concat(a, b);
+}
+
+export function maybe_map<T>(val: T[], fn: (v: T) => T) {
+  if (is_array(val)) {
+    const mapped = [];
+    for (let i = 0; i < val.length; i += 1) {
+      mapped.push(fn(val[i]!));
+    }
+    return mapped;
+  }
+  return fn(val);
+}

package/src/resources/alias/username/username.ts

@@ -11,6 +11,13 @@ export class Username extends APIResource {
 
   /**
    * Get basic details about a user, given their username
+   *
+   * @example
+   * ```ts
+   * const user = await client.alias.username.retrieve(
+   *   'username',
+   * );
+   * ```
    */
   retrieve(username: string, options?: Core.RequestOptions): Core.APIPromise<Shared.User> {
     return this._client.get(`/v1/alias/${username}`, options);

package/src/resources/alias/username/val-name.ts

@@ -7,6 +7,14 @@ import * as Shared from '../../shared';
 export class ValName extends APIResource {
   /**
    * Get a val
+   *
+   * @example
+   * ```ts
+   * const val = await client.alias.username.valName.retrieve(
+   *   'username',
+   *   'val_name',
+   * );
+   * ```
    */
   retrieve(username: string, valName: string, options?: Core.RequestOptions): Core.APIPromise<Shared.Val> {
     return this._client.get(`/v2/alias/vals/${username}/${valName}`, options);

package/src/resources/emails.ts

@@ -10,6 +10,15 @@ import * as Core from '../core';
 export class Emails extends APIResource {
   /**
    * Send emails
+   *
+   * @example
+   * ```ts
+   * const response = await client.emails.send({
+   *   html: 'Hello <strong>world</strong>',
+   *   subject: 'An important message',
+   *   text: 'Hello world',
+   * });
+   * ```
    */
   send(body?: EmailSendParams, options?: Core.RequestOptions): Core.APIPromise<EmailSendResponse>;
   send(options?: Core.RequestOptions): Core.APIPromise<EmailSendResponse>;

package/src/resources/index.ts

@@ -7,5 +7,11 @@ export { Emails, type EmailSendResponse, type EmailSendParams } from './emails';
 export { Me } from './me/me';
 export { Search } from './search/search';
 export { Sqlite, type SqliteBatchResponse, type SqliteBatchParams, type SqliteExecuteParams } from './sqlite';
+export {
+  TelemetryListResponsesPageCursorURL,
+  Telemetry,
+  type TelemetryListResponse,
+  type TelemetryListParams,
+} from './telemetry';
 export { Users } from './users';
-export { Vals, type ValCreateParams, type ValListParams } from './vals/vals';
+export { Vals, type ValListResponse, type ValCreateParams, type ValListParams } from './vals/vals';

package/src/resources/sqlite.ts

@@ -10,6 +10,14 @@ import * as Shared from './shared';
 export class Sqlite extends APIResource {
   /**
    * Execute a batch of SQLite statements and return results for all of them
+   *
+   * @example
+   * ```ts
+   * const resultSets = await client.sqlite.batch({
+   *   statements: ['SELECT 1;'],
+   *   mode: 'read',
+   * });
+   * ```
    */
   batch(body: SqliteBatchParams, options?: Core.RequestOptions): Core.APIPromise<SqliteBatchResponse> {
     return this._client.post('/v1/sqlite/batch', { body, ...options });
@@ -17,6 +25,13 @@ export class Sqlite extends APIResource {
 
   /**
    * Execute a single SQLite statement and return results
+   *
+   * @example
+   * ```ts
+   * const resultSet = await client.sqlite.execute({
+   *   statement: 'SELECT 1;',
+   * });
+   * ```
    */
   execute(body: SqliteExecuteParams, options?: Core.RequestOptions): Core.APIPromise<Shared.ResultSet> {
     return this._client.post('/v1/sqlite/execute', { body, ...options });

package/src/resources/telemetry.ts

@@ -0,0 +1,104 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../resource';
+import * as Core from '../core';
+import { PageCursorURL, type PageCursorURLParams } from '../pagination';
+
+/**
+ * OpenTelemetry traces for your val executions
+ */
+export class Telemetry extends APIResource {
+  /**
+   * Get OpenTelemetry traces for a given time window and filter by branch_id or
+   * file_id
+   */
+  list(
+    query: TelemetryListParams,
+    options?: Core.RequestOptions,
+  ): Core.PagePromise<TelemetryListResponsesPageCursorURL, TelemetryListResponse> {
+    return this._client.getAPIList('/v1/telemetry/traces', TelemetryListResponsesPageCursorURL, {
+      query,
+      ...options,
+    });
+  }
+}
+
+export class TelemetryListResponsesPageCursorURL extends PageCursorURL<TelemetryListResponse> {}
+
+export interface TelemetryListResponse {
+  attributes: Array<TelemetryListResponse.Attribute>;
+
+  endTimeUnixNano: string;
+
+  name: string;
+
+  startTimeUnixNano: string;
+
+  status: TelemetryListResponse.Status;
+
+  traceId: string;
+}
+
+export namespace TelemetryListResponse {
+  export interface Attribute {
+    key: string;
+
+    value: Attribute.Value;
+  }
+
+  export namespace Attribute {
+    export interface Value {
+      arrayValue?: unknown;
+
+      boolValue?: boolean;
+
+      bytesValue?: string;
+
+      doubleValue?: number;
+
+      intValue?: string;
+
+      kvlistValue?: unknown;
+
+      stringValue?: string;
+    }
+  }
+
+  export interface Status {
+    code: number;
+
+    message: string;
+  }
+}
+
+export interface TelemetryListParams extends PageCursorURLParams {
+  /**
+   * End date of the time window
+   */
+  end_timestamp: string;
+
+  /**
+   * Start date of the time window
+   */
+  start_timestamp: string;
+
+  /**
+   * Branch IDs to filter by
+   */
+  branch_ids?: Array<string>;
+
+  /**
+   * Include only traces from a given file identified by its ID
+   */
+  file_id?: string;
+}
+
+Telemetry.TelemetryListResponsesPageCursorURL = TelemetryListResponsesPageCursorURL;
+
+export declare namespace Telemetry {
+  export {
+    type TelemetryListResponse as TelemetryListResponse,
+    TelemetryListResponsesPageCursorURL as TelemetryListResponsesPageCursorURL,
+    type TelemetryListParams as TelemetryListParams,
+  };
+}

package/src/resources/users.ts

@@ -10,6 +10,13 @@ import * as Shared from './shared';
 export class Users extends APIResource {
   /**
    * Get basic information about a user
+   *
+   * @example
+   * ```ts
+   * const user = await client.users.retrieve(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   retrieve(userId: string, options?: Core.RequestOptions): Core.APIPromise<Shared.User> {
     return this._client.get(`/v1/users/${userId}`, options);

package/src/resources/vals/branches.ts

@@ -7,6 +7,17 @@ import { PageCursorURL, type PageCursorURLParams } from '../../pagination';
 export class Branches extends APIResource {
   /**
    * Create a new branch
+   *
+   * @example
+   * ```ts
+   * const branch = await client.vals.branches.create(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   {
+   *     name: 'my-branch',
+   *     branchId: '00000000-0000-0000-0000-000000000000',
+   *   },
+   * );
+   * ```
    */
   create(
     valId: string,
@@ -18,6 +29,14 @@ export class Branches extends APIResource {
 
   /**
    * Get a branch by id
+   *
+   * @example
+   * ```ts
+   * const branch = await client.vals.branches.retrieve(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   retrieve(
     valId: string,
@@ -29,6 +48,17 @@ export class Branches extends APIResource {
 
   /**
    * List all branches for a val
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const branchListResponse of client.vals.branches.list(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   { limit: 1, offset: 0 },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   list(
     valId: string,
@@ -43,6 +73,14 @@ export class Branches extends APIResource {
 
   /**
    * Delete a branch
+   *
+   * @example
+   * ```ts
+   * await client.vals.branches.delete(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
    */
   delete(valId: string, branchId: string, options?: Core.RequestOptions): Core.APIPromise<void> {
     return this._client.delete(`/v2/vals/${valId}/branches/${branchId}`, {

package/src/resources/vals/files.ts

@@ -8,6 +8,14 @@ import { type Response } from '../../_shims/index';
 export class Files extends APIResource {
   /**
    * Create a new file, project val or directory
+   *
+   * @example
+   * ```ts
+   * const file = await client.vals.files.create(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   { path: 'path', type: 'directory' },
+   * );
+   * ```
    */
   create(
     valId: string,
@@ -21,6 +29,17 @@ export class Files extends APIResource {
   /**
    * Get metadata for files and directories in a val. If path is an empty string,
    * returns files at the root directory.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const fileRetrieveResponse of client.vals.files.retrieve(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   { limit: 1, offset: 0, path: 'path', recursive: true },
+   * )) {
+   *   // ...
+   * }
+   * ```
    */
   retrieve(
     valId: string,
@@ -35,6 +54,14 @@ export class Files extends APIResource {
 
   /**
    * Update a file's content
+   *
+   * @example
+   * ```ts
+   * const file = await client.vals.files.update(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   { path: 'path' },
+   * );
+   * ```
    */
   update(
     valId: string,
@@ -49,6 +76,14 @@ export class Files extends APIResource {
    * Deletes a file or a directory. To delete a directory and all of its children,
    * use the recursive flag. To delete all files, pass in an empty path and the
    * recursive flag.
+   *
+   * @example
+   * ```ts
+   * await client.vals.files.delete(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   { path: 'path', recursive: true },
+   * );
+   * ```
    */
   delete(valId: string, params: FileDeleteParams, options?: Core.RequestOptions): Core.APIPromise<void> {
     const { path, recursive, branch_id } = params;
@@ -61,6 +96,17 @@ export class Files extends APIResource {
 
   /**
    * Download file content
+   *
+   * @example
+   * ```ts
+   * const response = await client.vals.files.getContent(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   { path: 'path' },
+   * );
+   *
+   * const content = await response.blob();
+   * console.log(content);
+   * ```
    */
   getContent(
     valId: string,

package/src/resources/vals/index.ts

@@ -21,4 +21,4 @@ export {
   type FileDeleteParams,
   type FileGetContentParams,
 } from './files';
-export { Vals, type ValCreateParams, type ValListParams } from './vals';
+export { Vals, type ValListResponse, type ValCreateParams, type ValListParams } from './vals';