@narrative.io/data-collaboration-sdk-ts 4.0.0-beta.0 → 4.0.0-beta.2

package/build/access-rules/index.d.ts

@@ -1,5 +1,5 @@
 import { BaseApi } from "../base-api";
-import type { ApiRecords, ApiRecordsV2, PaginationOptions } from "../types";
+import type { ApiRecords, ApiRecordsV2, PagePagination } from "../types";
 import type { AccessRule, AccessRuleMapping, AccessRuleMetadata, AccessRuleV2, CreateAccessRuleV2Request, OwnedAccessRule, SharedAccessRule, UpdateAccessRuleV2Request } from "./types";
 /**
  * Represents the parameters used to retrieve access rules.
@@ -104,7 +104,7 @@ declare class AccessRulesApi extends BaseApi {
      * @description This method fetches access rules based on the specified filters and pagination options provided in the parameters.
      *              It returns a promise that resolves to a list of access rules that match the criteria.
      */
-    getAccessableAccessRules(parameters: GetAccessRulesParameters & PaginationOptions): Promise<ApiRecordsV2<AccessRuleV2>>;
+    getAccessableAccessRules(parameters: GetAccessRulesParameters & PagePagination): Promise<ApiRecordsV2<AccessRuleV2>>;
     /**
      * Creates a new access rule (version 2).
      *

package/build/agents/index.d.ts

@@ -1,5 +1,5 @@
 import { BaseApi } from "../base-api";
-import type { ApiRecordsV2, PaginationOptions } from "../types";
+import type { ApiRecordsV2, PagePagination } from "../types";
 import type { ConversationId, ConversationResponse, CreateConversationRequest, CreateRunRequest, ListMessagesResponse, RunId, RunResponse } from "./types";
 export * from "./types";
 /**
@@ -23,7 +23,7 @@ export declare class AgentsApi extends BaseApi {
      * Scoped to both `company_id` and `user_id` from the bearer token — peers in
      * the same company are not visible. Never 404s; empty state is `records: []`.
      */
-    listAgentConversations(options?: PaginationOptions): Promise<ApiRecordsV2<ConversationResponse>>;
+    listAgentConversations(options?: PagePagination): Promise<ApiRecordsV2<ConversationResponse>>;
     /**
      * Read a conversation's metadata + current `version`. Always re-read this
      * immediately before starting a run — `version` is the compare-and-swap

package/build/agents/index.js

@@ -27,7 +27,7 @@ export class AgentsApi extends BaseApi {
      * the same company are not visible. Never 404s; empty state is `records: []`.
      */
     async listAgentConversations(options) {
-        return await this.get(conversationsResource, options ? { ...options } : undefined);
+        return await this.get(conversationsResource, options);
     }
     /**
      * Read a conversation's metadata + current `version`. Always re-read this

package/build/apps/index.js

@@ -15,9 +15,7 @@ class AppsApi extends BaseApi {
     async getApps(appCategory) {
         return appCategory === undefined
             ? await this.get(resourceName)
-            : await this.get(resourceName, {
-                category: appCategory,
-            });
+            : await this.get(resourceName, { category: appCategory });
     }
     /**
      * List installations for the authenticated company (or, with an app

package/build/base-api.d.ts

@@ -1,5 +1,5 @@
 import { HttpClient } from "./http-client";
-import type { Config, PaginationOptions } from "./types";
+import type { Config, QueryParamsOf } from "./types";
 /**
  * BaseApi class provides basic functionality for making API requests.
  */
@@ -48,11 +48,18 @@ export declare abstract class BaseApi {
     /**
      * Makes a GET request to the given endpoint.
      *
+     * `params` is constrained by its own values rather than by an index signature,
+     * so a purpose-built params interface can be passed directly — see
+     * {@link QueryParamsOf}. Pagination is *not* baked into this signature: the
+     * scheme differs per endpoint, so each params type declares its own (see
+     * `OffsetPagination` / `PagePagination` / `CursorPagination`).
+     *
      * @param {string} endpoint - Endpoint for the request.
      * @returns {Promise<T>} - Promise that resolves with the response data.
      * @template T - Type of the response data.
+     * @template P - Type of the query parameters.
      */
-    protected get<T>(endpoint: string, params?: Record<string, unknown> & PaginationOptions): Promise<T>;
+    protected get<T, P extends QueryParamsOf<P> = Record<string, never>>(endpoint: string, params?: P): Promise<T>;
     /**
      * Makes a POST request to the given endpoint with the given data.
      *
@@ -93,5 +100,11 @@ export declare abstract class BaseApi {
      * @private
      */
     private constructHeaders;
-    protected constructQueryString<T extends Record<string, unknown>>(parameters?: T): string;
+    /**
+     * Renders params into a query string, repeating array values (`?tag=a&tag=b`).
+     *
+     * Constrained by value rather than by index signature, for the reasons in
+     * {@link QueryParamsOf}.
+     */
+    protected constructQueryString<T extends QueryParamsOf<T> = Record<string, never>>(parameters?: T): string;
 }

package/build/base-api.js

@@ -78,9 +78,16 @@ export class BaseApi {
     /**
      * Makes a GET request to the given endpoint.
      *
+     * `params` is constrained by its own values rather than by an index signature,
+     * so a purpose-built params interface can be passed directly — see
+     * {@link QueryParamsOf}. Pagination is *not* baked into this signature: the
+     * scheme differs per endpoint, so each params type declares its own (see
+     * `OffsetPagination` / `PagePagination` / `CursorPagination`).
+     *
      * @param {string} endpoint - Endpoint for the request.
      * @returns {Promise<T>} - Promise that resolves with the response data.
      * @template T - Type of the response data.
+     * @template P - Type of the query parameters.
      */
     async get(endpoint, params) {
         const queryString = this.constructQueryString(params);
@@ -165,6 +172,12 @@ export class BaseApi {
         }
         return headers;
     }
+    /**
+     * Renders params into a query string, repeating array values (`?tag=a&tag=b`).
+     *
+     * Constrained by value rather than by index signature, for the reasons in
+     * {@link QueryParamsOf}.
+     */
     constructQueryString(parameters) {
         const queryParameters = [];
         if (parameters != null) {

package/build/companies/index.js

@@ -19,8 +19,6 @@ export class CompaniesApi extends BaseApi {
      *   applied server-side to the company name (`name_like` query param).
      */
     async getCompanies(nameLike) {
-        return await this.get(resourceName, {
-            name_like: nameLike,
-        });
+        return await this.get(resourceName, { name_like: nameLike });
     }
 }

package/build/compute-pools/types.d.ts

@@ -132,6 +132,10 @@ export interface UpdateComputePoolRequest {
 export interface ListComputePoolsResponse {
     records: ComputePoolResponse[];
 }
-export type ListComputePoolsParams = {
+export interface ListComputePoolsParams {
+    /**
+     * Documented by the public API, but the route does not currently read it —
+     * active compute pools are returned regardless of the value.
+     */
     status?: ComputePoolStatus;
-} & Record<string, unknown>;
+}

package/build/jobs/index.d.ts

@@ -1,13 +1,11 @@
 import { BaseApi } from "../base-api";
-import type { ApiRecordsV2 } from "../types";
+import type { ApiRecordsV2, OffsetPagination } from "../types";
 import type { CalculateAffectedRowsInput, CalculateAffectedRowsJob, CollectAccessRulesBillingDataInput, CollectAccessRulesBillingDataJob, CollectAccessRulesBillingDataResult, ColumnDetails, ColumnStatDataType, CostsInput, CostsJob, CreateTableInput, DatasetsCalculateColumnStatsJob, DatasetsCreateTableJob, DatasetsDeleteTableJob, DatasetsDeliverDataJob, DatasetsEnforceRowTtlRetentionPolicyJob, DatasetsEnforceTableTtlRetentionPolicyJob, DatasetsExecuteDmlJob, DatasetsExecuteSelectJob, DatasetsSampleJob, DatasetsSuggestMappingsJob, DatasetsTruncateTableJob, DeleteInput, DeliverInput, EnabledColumnStatFlags, EnforceRowTtlRetentionPolicyInput, EnforceTableTtlRetentionPolicyInput, ExecuteDmlInput, ExecuteDmlResult, ExecuteSelectInput, ExecuteSelectResult, ExplainInput, ExplainJob, ExplainOutput, ForecastInput, ForecastInternalJob, ForecastJob, HealthCheckJob, Job, JobExecutionCluster, JobRequestSource, JobRequestSourceApiUser, JobRequestSourceProcess, JobType, KnownJob, MaterializedViewInput, MaterializedViewJob, MaterializedViewOutput, MaterializedViewRowStats, ModelInferenceRunInput, ModelInferenceRunJob, ModelInferenceRunJobResult, ModelsDeliverModelInput, ModelsDeliverModelJob, ModelsTrainClassifierJob, ModelTrainingRunInput, ModelTrainingRunJob, RefreshMaterializedViewResult, SampleInput, StatsInput, StatsInputV2, SuggestMappingsInput, SuggestMappingsResult, TruncateTableInput } from "./types";
 import { isKnownJob, KNOWN_JOB_TYPES } from "./types";
 type JobStateFilter = "cancelled" | "completed" | "failed" | "pending" | "pending_cancellation" | "running" | "scheduled";
-interface GetJobsParameters extends Record<string, string | number | boolean | string[] | undefined> {
+interface GetJobsParameters extends OffsetPagination {
     data_plane_id?: string;
     dataset_id?: number;
-    per_page?: number;
-    offset?: number;
     order_by?: "created_at_asc" | "created_at_desc" | "updated_at_asc" | "updated_at_desc";
     state?: JobStateFilter | JobStateFilter[];
     type?: string | string[];

package/build/types.d.ts

@@ -59,10 +59,67 @@ export interface PaginationMetadata {
     total_records: number;
     total_pages: number;
 }
-export interface PaginationOptions {
+/**
+ * A value that can be rendered into a query string.
+ *
+ * Arrays are repeated (`?tag=a&tag=b`) rather than joined, matching how the
+ * backend's `OptionalMultiQueryParamDecoderMatcher` reads them.
+ */
+export type QueryValue = string | number | boolean | null | undefined | Array<string | number | boolean>;
+/**
+ * Constrains a params type's *values* to what a query string can express, without
+ * requiring an index signature.
+ *
+ * This is a homomorphic mapped type, so it preserves optional modifiers and maps
+ * only over `P`'s own keys. That's the difference that matters: a plain interface
+ * satisfies it, whereas `Record<string, unknown>` requires an index signature that
+ * TypeScript never gives an interface — and an index signature would also disable
+ * excess-property checking, silently accepting misspelled parameter names.
+ */
+export type QueryParamsOf<P> = {
+    [K in keyof P]: QueryValue;
+};
+/**
+ * `per_page` + `offset`. Server defaults: `per_page` 50, `offset` 0.
+ *
+ * The original pagination scheme (`http4s.pagination`), used by billing,
+ * contracts, dataset snapshots, dataset stats, data streams, jobs and product
+ * admin. Sending `page` to one of these endpoints does nothing — it is ignored
+ * and you get the first page every time.
+ */
+export interface OffsetPagination {
+    per_page?: number | null;
+    offset?: number | null;
+}
+/**
+ * `per_page` + `page`. Server default: `page` 1, page size per route.
+ *
+ * The `http4s.paginationV2` scheme, and the most common one: access rules,
+ * agents, app invites, attributes, datasets, installations, models, queries,
+ * views and the workflows list.
+ */
+export interface PagePagination {
     page?: number | null;
     per_page?: number | null;
 }
+/**
+ * `per_page` + `page_token`. Server default: `per_page` 10.
+ *
+ * Opaque-cursor pagination. Read `next_page_token` off the response and pass it
+ * back as `page_token`; a null/absent token means the last page.
+ */
+export interface CursorPagination {
+    per_page?: number;
+    page_token?: string;
+}
+/**
+ * Page-number pagination.
+ *
+ * @deprecated Prefer {@link PagePagination}, which names the scheme explicitly.
+ * Not every endpoint paginates this way — see {@link OffsetPagination} and
+ * {@link CursorPagination}.
+ */
+export type PaginationOptions = PagePagination;
 /**
  * Interface for search parameters
  */

package/build/workflows/types.d.ts

@@ -53,13 +53,21 @@ export interface ListRunsResponse {
     runs: WorkflowRun[];
     next_page_token?: string | null;
 }
-export interface ListRunsParams extends Record<string, unknown> {
+/**
+ * Query parameters for `GET /workflows/{id}/runs`.
+ *
+ * Deliberately has no index signature: an index signature would silently accept
+ * misspelled or legacy parameter names (e.g. `pageSize`/`pageToken`), which the
+ * server ignores — the request succeeds and pagination just never advances.
+ */
+export interface ListRunsParams {
     /** Maximum number of runs to return per page (`per_page` query param). Defaults to 10. */
     per_page?: number;
     /** Opaque token from a previous response (`page_token` query param). */
     page_token?: string;
 }
-export interface ListWorkflowsParams extends PaginationOptions, Record<string, unknown> {
+/** Query parameters for `GET /workflows`. See {@link ListRunsParams} on why there's no index signature. */
+export interface ListWorkflowsParams extends PaginationOptions {
     /** Narrow results to workflows on this data plane. */
     data_plane_id?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "4.0.0-beta.0",
+	"version": "4.0.0-beta.2",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",