postgrid-node 0.1.0-alpha.5 → 0.2.0

package/src/resources/print-mail/reports/reports.ts

@@ -0,0 +1,290 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as ExportsAPI from './exports';
+import {
+  ExportCreateParams,
+  ExportDeleteParams,
+  ExportRetrieveParams,
+  Exports,
+  ReportExport,
+} from './exports';
+import * as SamplesAPI from './samples';
+import { ReportSample, ReportSampleCreateBase, SampleCreateParams, Samples } from './samples';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Reports extends APIResource {
+  samples: SamplesAPI.Samples = new SamplesAPI.Samples(this._client);
+  exports: ExportsAPI.Exports = new ExportsAPI.Exports(this._client);
+
+  /**
+   * Create a new saved report definition. Saved reports are SQL queries that can be
+   * executed later to generate full exports or samples.
+   *
+   * If you just want to do ad-hoc queries, you should use the `/reports/samples`
+   * endpoint.
+   *
+   * @example
+   * ```ts
+   * const report = await client.printMail.reports.create({
+   *   sqlQuery:
+   *     'SELECT id, status FROM orders WHERE created_at > ?',
+   *   description: 'Recent Orders',
+   *   metadata: { team: 'Sales' },
+   * });
+   * ```
+   */
+  create(body: ReportCreateParams, options?: RequestOptions): APIPromise<Report> {
+    return this._client.post('/print-mail/v1/reports', { body, ...options });
+  }
+
+  /**
+   * Retrieve the details of a specific saved report by its ID.
+   *
+   * @example
+   * ```ts
+   * const report = await client.printMail.reports.retrieve(
+   *   'id',
+   * );
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<Report> {
+    return this._client.get(path`/print-mail/v1/reports/${id}`, options);
+  }
+
+  /**
+   * Update an existing saved report definition. You can change the query,
+   * description, or metadata.
+   *
+   * @example
+   * ```ts
+   * const report = await client.printMail.reports.update('id', {
+   *   description: 'Recent Orders (Updated)',
+   * });
+   * ```
+   */
+  update(id: string, body: ReportUpdateParams, options?: RequestOptions): APIPromise<Report> {
+    return this._client.post(path`/print-mail/v1/reports/${id}`, { body, ...options });
+  }
+
+  /**
+   * Retrieve a list of saved reports for your organization.
+   *
+   * @example
+   * ```ts
+   * const reports = await client.printMail.reports.list();
+   * ```
+   */
+  list(
+    query: ReportListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ReportListResponse> {
+    return this._client.get('/print-mail/v1/reports', { query, ...options });
+  }
+
+  /**
+   * Delete a saved report definition. This action cannot be undone. Associated
+   * exports are not automatically deleted.
+   *
+   * @example
+   * ```ts
+   * const deletedResponse =
+   *   await client.printMail.reports.delete('id');
+   * ```
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<DeletedResponse> {
+    return this._client.delete(path`/print-mail/v1/reports/${id}`, options);
+  }
+
+  /**
+   * Run an ad-hoc SQL query against your data lake and get a sample of the results.
+   * This is useful for quickly testing queries without saving them as a report. The
+   * query execution time and result size are limited.
+   *
+   * @example
+   * ```ts
+   * const reportSample = await client.printMail.reports.sample({
+   *   sqlQuery: 'SELECT id FROM contacts LIMIT 5',
+   *   limit: 5,
+   *   params: [],
+   * });
+   * ```
+   */
+  sample(body: ReportSampleParams, options?: RequestOptions): APIPromise<SamplesAPI.ReportSample> {
+    return this._client.post('/print-mail/v1/reports/samples', { body, ...options });
+  }
+}
+
+/**
+ * Generic response for delete operations.
+ */
+export interface DeletedResponse {
+  /**
+   * The ID of the deleted resource.
+   */
+  id: string;
+
+  /**
+   * Indicates the resource was successfully deleted.
+   */
+  deleted: true;
+}
+
+/**
+ * Represents a saved Report definition.
+ */
+export interface Report {
+  /**
+   * Unique identifier for the report.
+   */
+  id: string;
+
+  /**
+   * Timestamp when the report was created.
+   */
+  createdAt: string;
+
+  /**
+   * Indicates if the report is associated with the live or test environment.
+   */
+  live: boolean;
+
+  /**
+   * Always `report`.
+   */
+  object: 'report';
+
+  /**
+   * The SQL query defining the report.
+   */
+  sqlQuery: string;
+
+  /**
+   * Timestamp when the report was last updated.
+   */
+  updatedAt: string;
+
+  /**
+   * An optional user-friendly description for the report.
+   */
+  description?: string;
+
+  /**
+   * Optional key-value metadata associated with the report.
+   */
+  metadata?: { [key: string]: string };
+}
+
+/**
+ * Represents a list of Reports.
+ */
+export interface ReportListResponse {
+  data: Array<Report>;
+
+  limit: number;
+
+  object: 'list';
+
+  skip: number;
+
+  totalCount: number;
+}
+
+export interface ReportCreateParams {
+  /**
+   * The SQL query defining the report.
+   */
+  sqlQuery: string;
+
+  /**
+   * An optional user-friendly description for the report.
+   */
+  description?: string;
+
+  /**
+   * Optional key-value metadata associated with the report.
+   */
+  metadata?: { [key: string]: string };
+}
+
+export interface ReportUpdateParams {
+  /**
+   * An optional user-friendly description for the report. Set to null to remove.
+   */
+  description?: string | null;
+
+  /**
+   * Optional key-value metadata associated with the report. Set to null to remove.
+   */
+  metadata?: { [key: string]: string } | null;
+
+  /**
+   * The SQL query defining the report.
+   */
+  sqlQuery?: string;
+}
+
+export interface ReportListParams {
+  limit?: number;
+
+  /**
+   * You can supply any string to help narrow down the list of resources. For
+   * example, if you pass `"New York"` (quoted), it will return resources that have
+   * that string present somewhere in their response. Alternatively, you can supply a
+   * structured search query. See the documentation on `StructuredSearchQuery` for
+   * more details.
+   */
+  search?: string;
+
+  skip?: number;
+}
+
+export interface ReportSampleParams {
+  /**
+   * The SQL query to execute for the sample.
+   */
+  sqlQuery: string;
+
+  /**
+   * Maximum number of rows to return in the sample.
+   */
+  limit?: number;
+
+  /**
+   * Optional parameters to bind to the SQL query (e.g., for placeholders like ? or
+   * $1).
+   */
+  params?: Array<string>;
+}
+
+Reports.Samples = Samples;
+Reports.Exports = Exports;
+
+export declare namespace Reports {
+  export {
+    type DeletedResponse as DeletedResponse,
+    type Report as Report,
+    type ReportListResponse as ReportListResponse,
+    type ReportCreateParams as ReportCreateParams,
+    type ReportUpdateParams as ReportUpdateParams,
+    type ReportListParams as ReportListParams,
+    type ReportSampleParams as ReportSampleParams,
+  };
+
+  export {
+    Samples as Samples,
+    type ReportSample as ReportSample,
+    type ReportSampleCreateBase as ReportSampleCreateBase,
+    type SampleCreateParams as SampleCreateParams,
+  };
+
+  export {
+    Exports as Exports,
+    type ReportExport as ReportExport,
+    type ExportCreateParams as ExportCreateParams,
+    type ExportRetrieveParams as ExportRetrieveParams,
+    type ExportDeleteParams as ExportDeleteParams,
+  };
+}

package/src/resources/print-mail/reports/samples.ts

@@ -0,0 +1,84 @@
+// 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 { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Samples extends APIResource {
+  /**
+   * Run the query associated with a saved report and get a sample of the results.
+   * This allows getting up to 1000 rows of resutls but the runtime of the query is
+   * limited to 30 seconds. If you need more rows or longer runtime, you should
+   * create an export from this report.
+   *
+   * @example
+   * ```ts
+   * const reportSample =
+   *   await client.printMail.reports.samples.create('id', {
+   *     limit: 10,
+   *     params: ['2023-10-01T00:00:00Z'],
+   *   });
+   * ```
+   */
+  create(id: string, body: SampleCreateParams, options?: RequestOptions): APIPromise<ReportSample> {
+    return this._client.post(path`/print-mail/v1/reports/${id}/samples`, { body, ...options });
+  }
+}
+
+/**
+ * Represents the result of a report sample query.
+ */
+export interface ReportSample {
+  /**
+   * Unique identifier for the sample query result.
+   */
+  id: string;
+
+  /**
+   * The actual data records returned by the sample query.
+   */
+  records: Array<{ [key: string]: unknown }>;
+
+  /**
+   * The ID of the report this sample was generated from, or null for ad-hoc samples.
+   */
+  report: string | null;
+}
+
+/**
+ * Base properties for creating a report sample.
+ */
+export interface ReportSampleCreateBase {
+  /**
+   * Maximum number of rows to return in the sample.
+   */
+  limit?: number;
+
+  /**
+   * Optional parameters to bind to the SQL query (e.g., for placeholders like ? or
+   * $1).
+   */
+  params?: Array<string>;
+}
+
+export interface SampleCreateParams {
+  /**
+   * Maximum number of rows to return in the sample.
+   */
+  limit?: number;
+
+  /**
+   * Optional parameters to bind to the SQL query (e.g., for placeholders like ? or
+   * $1).
+   */
+  params?: Array<string>;
+}
+
+export declare namespace Samples {
+  export {
+    type ReportSample as ReportSample,
+    type ReportSampleCreateBase as ReportSampleCreateBase,
+    type SampleCreateParams as SampleCreateParams,
+  };
+}