@paid-ai/paid-node 1.7.0 → 1.8.0

package/dist/esm/api/resources/customViewsExperimental/client/Client.d.mts

@@ -0,0 +1,177 @@
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient.mjs";
+import * as core from "../../../../core/index.mjs";
+import * as Paid from "../../../index.mjs";
+export declare namespace CustomViewsExperimental {
+    interface Options extends BaseClientOptions {
+    }
+    interface RequestOptions extends BaseRequestOptions {
+    }
+}
+export declare class CustomViewsExperimental {
+    protected readonly _options: CustomViewsExperimental.Options;
+    constructor(_options: CustomViewsExperimental.Options);
+    /**
+     * ⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.
+     *
+     * Lists the organization's custom views (newest first) with lightweight summary info — name, status, query count, default date range, created date. Does not return the SQL or render bundle; fetch a single view via getCustomView for those.
+     *
+     * @param {CustomViewsExperimental.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.customViewsExperimental.listCustomViews()
+     */
+    listCustomViews(requestOptions?: CustomViewsExperimental.RequestOptions): core.HttpResponsePromise<Paid.CustomViewListResponse>;
+    private __listCustomViews;
+    /**
+     * ⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.
+     *
+     * ⚠️ Only call this when the user has EXPLICITLY asked to save or create the view. After generating or previewing a dashboard, do NOT automatically save it — show it to the user and wait for them to ask you to save it. A customer-scoped view is created as a DRAFT — creating it is NOT permission to publish; never chain a publish onto a create. An organization-scoped view is created already PUBLISHED instead: it has no draft state and no publish step at all (never call publishCustomView on one — it's a no-op, and unpublishView refuses it outright). After saving, hand the user the previewUrl and wait for their feedback before doing anything else. Saves named analytics queries + a self-contained HTML render bundle. **Call getCustomViewAuthoringGuide (GET /experimental/views/authoring-guide) first** — it returns the full guide and a copy-paste interactive template. Key rules: (1) Do NOT add a customer filter to the SQL — the database scopes every query to the viewing customer at embed time. (2) Each query's SQL must be SELECT-only; return clearly-named columns. Compute metric VALUES in SQL (e.g. (count()*2)/5 AS custom_metric) — derive a number in the render bundle only when it depends on user interaction (toggle/filter/hover) or is pure formatting of a value a query already returns. (3) The render bundle must be SELF-CONTAINED — inline all CSS/JS/charting, NO external loads or fetch (the sandbox has connect-src 'none'); it must listen for the `paid:data` message (data keyed by query id) and re-render on each one. (4) Make it INTERACTIVE — mousemove hover tooltips and at least one addEventListener-wired control that re-renders (a static chart feels broken). (5) The render bundle is the single source of truth — BEFORE saving, preview the EXACT bundle in the user's current client (call getCustomViewPreviewHarness with your bundle + sample data and render the HTML it returns) and show it to the user; that preview in the current client is how the user first sees the dashboard. Do NOT save a draft just to preview it in Paid — creating writes to the user's real account and is never a preview step. Do NOT build a separate chart, and only show numbers that come from a declared query. (6) A view is a FULL dashboard — include as many charts/KPIs as the analysis has. Keep every element derived from the single viewing customer (KPIs, trends, type mix); drop only cross-customer comparisons (rankings, share-of-total, 'N customers'). Don't simplify to one chart. (7) To make the date range adjustable (e.g. the user says 'last month'), write the date boundary as `{period_start:DateTime}` / `{period_end:DateTime}` placeholders in the SQL and pass a default `period` (relative like {kind:'relative',unit:'month',amount:1}, or absolute start/end). The org user can then change it in Paid without re-authoring. A query using the placeholders REQUIRES a period. Do NOT add your own date-range picker to the render bundle — Paid owns the timeframe and the bundle receives already-filtered data; a second in-bundle picker cannot re-run the SQL. (8) Check your draft with validateCustomView (POST /experimental/views/validate) BEFORE asking the user to save — it runs these same gates without persisting and reports every problem at once. The response returns a `previewUrl` — give it to the user so they can open the new view in Paid.
+     *
+     * @param {Paid.CreateCustomViewRequest} request
+     * @param {CustomViewsExperimental.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.customViewsExperimental.createCustomView({
+     *         name: "Usage over time",
+     *         queries: [{
+     *                 id: "usage",
+     *                 sql: "SELECT toDate(created_at) AS day, count() AS signals FROM fact_signal GROUP BY day ORDER BY day"
+     *             }],
+     *         renderBundle: "<!doctype html><body>\u2026</body>"
+     *     })
+     */
+    createCustomView(request: Paid.CreateCustomViewRequest, requestOptions?: CustomViewsExperimental.RequestOptions): core.HttpResponsePromise<Paid.CustomView>;
+    private __createCustomView;
+    /**
+     * ⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.
+     *
+     * ⚠️ Never publish as an automatic follow-up to creating or generating a view. Only call this after you have shown the user the built/previewed view and they have EXPLICITLY approved publishing — building and publishing are separate user decisions, and answering an earlier question (e.g. the view's scope) is NOT publish approval. Flips the view from DRAFT to PUBLISHED. Only PUBLISHED views are served on the embed data path — this is the gate that stops an unreviewed view reaching end-customers. Idempotent: publishing an already-published view is a no-op success. The response returns a `previewUrl` — give it to the user so they can open the view in Paid.
+     *
+     * @param {Paid.PublishCustomViewRequest} request
+     * @param {CustomViewsExperimental.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.customViewsExperimental.publishCustomView({
+     *         displayId: "displayId"
+     *     })
+     */
+    publishCustomView(request: Paid.PublishCustomViewRequest, requestOptions?: CustomViewsExperimental.RequestOptions): core.HttpResponsePromise<Paid.CustomView>;
+    private __publishCustomView;
+    /**
+     * ⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.
+     *
+     * Updates the view's default date range (the period applied to queries that use the `{period_start:DateTime}` / `{period_end:DateTime}` placeholders). Accepts a relative rolling window (e.g. last 30 days) or a fixed start/end range. Lets the period be changed after deployment without re-authoring the SQL. Applies to DRAFT or PUBLISHED views.
+     *
+     * @param {Paid.UpdateCustomViewPeriodRequest} request
+     * @param {CustomViewsExperimental.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.customViewsExperimental.updateCustomViewPeriod({
+     *         displayId: "displayId",
+     *         period: {
+     *             kind: "relative"
+     *         }
+     *     })
+     */
+    updateCustomViewPeriod(request: Paid.UpdateCustomViewPeriodRequest, requestOptions?: CustomViewsExperimental.RequestOptions): core.HttpResponsePromise<Paid.CustomView>;
+    private __updateCustomViewPeriod;
+    /**
+     * ⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.
+     *
+     * Returns the view's name, status, query ids, and the author render bundle for the owning organization (DRAFT or PUBLISHED). Used by the trusted preview/embed frame to render the sandbox; the per-customer data is fetched separately via /:displayId/data.
+     *
+     * @param {Paid.GetCustomViewRequest} request
+     * @param {CustomViewsExperimental.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.customViewsExperimental.getCustomView({
+     *         displayId: "displayId"
+     *     })
+     */
+    getCustomView(request: Paid.GetCustomViewRequest, requestOptions?: CustomViewsExperimental.RequestOptions): core.HttpResponsePromise<Paid.CustomViewDetail>;
+    private __getCustomView;
+    /**
+     * ⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.
+     *
+     * Partially updates a view. Omitted fields are left unchanged. For REVISIONS, prefer the incremental fields — `bundleEdits` (exact search-and-replace on the stored render bundle) and `queryUpserts`/`queryRemovals` (per-query changes) — so you transmit only what changed instead of re-sending the whole payload. The full-replacement fields remain for rewrites: `renderBundle`, and `queries` (a FULL replacement of the query list — never drop queries the user didn't ask to remove). Replacement and incremental forms of the same aspect cannot be combined. The resulting SQL and bundle pass the same validation as createCustomView (SELECT-only, size cap, self-contained, paid:data listener). Works on DRAFT or PUBLISHED views — published embeds pick the change up on their next load.
+     *
+     * @param {Paid.UpdateCustomViewRequest} request
+     * @param {CustomViewsExperimental.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.customViewsExperimental.updateCustomView({
+     *         displayId: "displayId"
+     *     })
+     */
+    updateCustomView(request: Paid.UpdateCustomViewRequest, requestOptions?: CustomViewsExperimental.RequestOptions): core.HttpResponsePromise<Paid.CustomView>;
+    private __updateCustomView;
+    /**
+     * ⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.
+     *
+     * Runs every stored query of the view on the read-only analytics database and returns the result sets keyed by query id. For a customer-scoped view (the default), the query is scoped to the caller's organization AND the given `customerId` (both enforced as ClickHouse row filters) — `customerId` is required. For an organization-scoped view, the data is org-wide (scoped only to the caller's organization) and `customerId` is ignored. The scope is enforced by the database — it cannot be widened by the stored SQL. If the view declares filters, pass per-request values as `filter_<name>` query parameters (e.g. `filter_region=eu`); undeclared names or disallowed values are rejected with 400. Filters narrow data within the scope — never widen it.
+     *
+     * @param {Paid.GetCustomViewDataRequest} request
+     * @param {CustomViewsExperimental.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.RequestTimeoutError}
+     * @throws {@link Paid.TooManyRequestsError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.customViewsExperimental.getCustomViewData({
+     *         displayId: "displayId"
+     *     })
+     */
+    getCustomViewData(request: Paid.GetCustomViewDataRequest, requestOptions?: CustomViewsExperimental.RequestOptions): core.HttpResponsePromise<Paid.ViewDataResponse>;
+    private __getCustomViewData;
+    /**
+     * ⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.
+     *
+     * Mints a short-lived, customer-scoped token for embedding a published custom view. Call this from your server with your API key, then pass the returned token to the embed SDK. Organization-scoped views cannot be embedded per-customer — this returns a 400 (`ORG_SCOPED_VIEW_NOT_EMBEDDABLE`) for one.
+     *
+     * @param {Paid.GetCustomViewEmbedTokenRequest} request
+     * @param {CustomViewsExperimental.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link Paid.BadRequestError}
+     * @throws {@link Paid.ForbiddenError}
+     * @throws {@link Paid.NotFoundError}
+     * @throws {@link Paid.InternalServerError}
+     *
+     * @example
+     *     await client.customViewsExperimental.getCustomViewEmbedToken({
+     *         displayId: "displayId",
+     *         customerId: "customerId"
+     *     })
+     */
+    getCustomViewEmbedToken(request: Paid.GetCustomViewEmbedTokenRequest, requestOptions?: CustomViewsExperimental.RequestOptions): core.HttpResponsePromise<Paid.CustomViewEmbedTokenResponse>;
+    private __getCustomViewEmbedToken;
+    protected _getAuthorizationHeader(): Promise<string>;
+}