@cube-nl/dmp-sdk 0.0.0-stage → 1.0.0-rc.4

package/dist/query.d.ts

@@ -0,0 +1,9 @@
+import type { AggregateQuery, GetQuery, ListQuery } from './types.js';
+/**
+ * Turn a query description into cube/api's query string, without the leading `?`.
+ *
+ * Mistakes the API would refuse anyway, and that this SDK can see coming, are thrown here as a
+ * TypeError before a request is made: a bare array as a filter value (`filter[x][]=a` names no
+ * operator and is refused — write `{ in: [...] }`), or a list under an operator that takes one value.
+ */
+export declare function buildQuery(resource: string, query?: ListQuery & GetQuery & Partial<AggregateQuery>): string;

package/dist/query.js

@@ -0,0 +1,121 @@
+const LIST_OPERATORS = new Set(['in', 'between']);
+/**
+ * Turn a query description into cube/api's query string, without the leading `?`.
+ *
+ * Mistakes the API would refuse anyway, and that this SDK can see coming, are thrown here as a
+ * TypeError before a request is made: a bare array as a filter value (`filter[x][]=a` names no
+ * operator and is refused — write `{ in: [...] }`), or a list under an operator that takes one value.
+ */
+export function buildQuery(resource, query = {}) {
+    const params = new URLSearchParams();
+    appendFields(params, resource, query.fields);
+    appendFilters(params, query.filter);
+    appendList(params, 'sort', query.sort);
+    appendList(params, 'include', query.include);
+    appendList(params, 'with_count', query.withCount);
+    appendHas(params, query.has);
+    appendList(params, 'fn', query.fn);
+    appendList(params, 'group', query.group);
+    if (query.page?.size !== undefined) {
+        params.append('page[size]', String(query.page.size));
+    }
+    if (query.page?.number !== undefined) {
+        params.append('page[number]', String(query.page.number));
+    }
+    for (const [key, value] of Object.entries(query.params ?? {})) {
+        params.append(key, value);
+    }
+    // The API reads both forms; the raw one is what the README and the error messages show. All
+    // four characters are legal unescaped in a query string (RFC 3986 section 3.4).
+    return params
+        .toString()
+        .replace(/%5B/gi, '[')
+        .replace(/%5D/gi, ']')
+        .replace(/%2C/gi, ',')
+        .replace(/%28/gi, '(')
+        .replace(/%29/gi, ')');
+}
+function appendFields(params, resource, fields) {
+    if (fields === undefined) {
+        return;
+    }
+    const perResource = isStringArray(fields) ? { [resource]: fields } : fields;
+    for (const [name, list] of Object.entries(perResource)) {
+        if (list.length > 0) {
+            params.append(`fields[${name}]`, list.join(','));
+        }
+    }
+}
+function appendFilters(params, filter) {
+    for (const [field, value] of Object.entries(filter ?? {})) {
+        if (Array.isArray(value)) {
+            throw new TypeError(`filter.${field}: a bare list names no operator and cube/api refuses it. `
+                + `Write { in: [...] } (or { between: [from, to] }).`);
+        }
+        if (value === null || value === undefined) {
+            throw new TypeError(`filter.${field}: write { is: 'null' } or { is: 'not_null' } to filter on null.`);
+        }
+        if (typeof value !== 'object') {
+            params.append(`filter[${field}]`, scalar(value));
+            continue;
+        }
+        for (const [operator, operand] of Object.entries(value)) {
+            if (operand === undefined) {
+                continue;
+            }
+            params.append(`filter[${field}][${operator}]`, operatorValue(field, operator, operand));
+        }
+    }
+}
+function operatorValue(field, operator, operand) {
+    if (operand === null) {
+        if (operator !== 'is') {
+            throw new TypeError(`filter.${field}.${operator}: null is only meaningful under 'is'.`);
+        }
+        return 'null';
+    }
+    if (Array.isArray(operand)) {
+        if (!LIST_OPERATORS.has(operator)) {
+            throw new TypeError(`filter.${field}.${operator}: takes one value; only 'in' and 'between' take a list.`);
+        }
+        return operand.map(scalar).join(',');
+    }
+    return scalar(operand);
+}
+function appendHas(params, has) {
+    for (const [relation, value] of Object.entries(has ?? {})) {
+        if (value === true) {
+            params.append(`has[${relation}]`, '1');
+        }
+        else if (typeof value === 'number') {
+            params.append(`has[${relation}][min]`, String(value));
+        }
+        else {
+            if (value.min !== undefined) {
+                params.append(`has[${relation}][min]`, String(value.min));
+            }
+            if (value.max !== undefined) {
+                params.append(`has[${relation}][max]`, String(value.max));
+            }
+        }
+    }
+}
+function appendList(params, key, value) {
+    if (value === undefined) {
+        return;
+    }
+    const joined = typeof value === 'string' ? value : value.filter((item) => item !== '').join(',');
+    if (joined !== '') {
+        params.append(key, joined);
+    }
+}
+/** Booleans as 1/0, which is what the API's own examples (`filter[active]=1`) use. */
+function scalar(value) {
+    if (typeof value === 'boolean') {
+        return value ? '1' : '0';
+    }
+    return String(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value);
+}

package/dist/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * The wire format of cube/api on 5.0.x, as types. Field names are the API's own (snake_case),
+ * deliberately not camelCased: a caller reading the README, `_capabilities` or a raw response in
+ * the network tab sees the same names here.
+ */
+/** A record as the API returns it. Plug in your own type with the generic on `resources<T>()`. */
+export type DmpRecord = Record<string, unknown>;
+/** Every filter operator `filter[{field}][{operator}]` accepts (`_capabilities.operators`). */
+export type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'like' | 'ilike' | 'is' | 'between';
+export type Scalar = string | number | boolean;
+/**
+ * One field's filter.
+ *
+ * - a scalar: equality, `filter[status]=active` (a string may carry a prefix such as `'>=4'`);
+ * - an object of named operators: `{ gte: 8, lte: 10 }` gives `filter[hours][gte]=8&filter[hours][lte]=10`.
+ *   `in` and `between` take an array, `is` takes `'null'`, `'not_null'` or `null`.
+ */
+export type FilterValue = Scalar | {
+    [operator in FilterOperator]?: Scalar | readonly Scalar[] | null;
+};
+export interface PageQuery {
+    /** Default 50, maximum 200 (see `_capabilities.pagination`). Above the maximum is a 422, never a clamp. */
+    size?: number;
+    /** From 1. */
+    number?: number;
+}
+/** `has[{relation}]`: `true` is "has any", a number is "at least", `{ min, max }` a range. */
+export type HasValue = true | number | {
+    min?: number;
+    max?: number;
+};
+export interface ListQuery {
+    /**
+     * `fields[{resource}]`. An array applies to the resource being queried. cube/api reads only the
+     * queried resource's entry: an included relation always comes back with its own summary.
+     */
+    fields?: readonly string[] | Record<string, readonly string[]>;
+    filter?: Record<string, FilterValue>;
+    /** `'title'` or `'-title'` for descending; several are applied in order. */
+    sort?: string | readonly string[];
+    page?: PageQuery;
+    /** Relations, one level deep. */
+    include?: string | readonly string[];
+    /** Has-many relations to count; each row gets `{relation}_aantal`, which is also sortable. */
+    withCount?: string | readonly string[];
+    has?: Record<string, HasValue>;
+    /**
+     * Raw query parameters, appended last. For a parameter this SDK does not know yet; prefer the
+     * typed options above.
+     */
+    params?: Record<string, string>;
+}
+export interface GetQuery {
+    fields?: readonly string[] | Record<string, readonly string[]>;
+    include?: string | readonly string[];
+    withCount?: string | readonly string[];
+    params?: Record<string, string>;
+}
+export interface AggregateQuery {
+    /** `count`, `sum(hours)`, `avg(hours)`, `min(x)`, `max(x)`. The response keys are exactly these strings. */
+    fn: string | readonly string[];
+    /** Dimensions, optionally truncated: `department_id`, `started_on.month`. */
+    group?: string | readonly string[];
+    filter?: Record<string, FilterValue>;
+    has?: Record<string, HasValue>;
+    params?: Record<string, string>;
+}
+export interface PageMeta {
+    size: number;
+    number: number;
+    /** Rows in the whole scoped and filtered set, not on this page. */
+    total: number;
+    pages: number;
+}
+export interface Meta {
+    resource: string;
+    contract: string;
+    page?: PageMeta | null;
+    /** `_aggregate` only. */
+    groups?: number | null;
+    /** Requested relations that came back with no data because the caller may not see them. */
+    omitted?: string[];
+    /** Relations that came back but are not guaranteed complete ("3 of 8 shown"). */
+    pruned?: string[];
+    /** Fields the caller may not read, withheld from an otherwise normal 200. */
+    forbidden_fields?: string[];
+}
+export interface RateLimit {
+    limit: number | null;
+    remaining: number | null;
+    reset: number | null;
+}
+/** What every successful call returns: the body's `data`/`meta` plus the headers that matter. */
+export interface DmpResponse<T> {
+    status: number;
+    data: T;
+    meta: Meta | null;
+    headers: Headers;
+    /** Weak representation validator. For `If-None-Match`, never for `If-Match`. */
+    etag: string | null;
+    /** Strong record validator: what `ifMatch` takes. On detail, create, update and a 409. */
+    recordVersion: string | null;
+    /** On a 201: the new record's absolute URL (`https://dmp.example.nl/apps/api/v1/projects/7`). */
+    location: string | null;
+    /** `Idempotency-Replayed: true`: this is the stored answer to an earlier attempt, nothing was written now. */
+    replayed: boolean;
+    rateLimit: RateLimit;
+}
+export interface ListResponse<T> extends DmpResponse<T[]> {
+    meta: Meta & {
+        page: PageMeta;
+    };
+}
+export interface OperationResponse<T> extends DmpResponse<T | null> {
+    /** 202: the work was queued, not done. */
+    accepted: boolean;
+}
+export interface FieldCapability {
+    name: string;
+    /** A JSON Schema primitive, or several joined with `|` for a union (`string|integer`). */
+    type: string;
+    nullable: boolean;
+    readonly: boolean;
+    description?: string | null;
+}
+export interface OperationCapability {
+    name: string;
+    description: string;
+    target: 'record' | 'collection';
+    /** false: `Idempotency-Key` is required, not merely honoured. */
+    idempotent: boolean;
+    input: Record<string, unknown>;
+    required: string[];
+    /** The resource it answers with; null means 204. */
+    output?: string | null;
+}
+export interface ResourceCapability {
+    name: string;
+    description: string;
+    actions: Array<'list' | 'get' | 'create' | 'update' | 'delete' | (string & {})>;
+    operations: OperationCapability[];
+    fields: FieldCapability[];
+    summary: string[];
+    filterable: string[];
+    sortable: string[];
+    groupable: string[];
+    aggregatable: Record<string, string[]>;
+    relations: Record<string, {
+        resource: string;
+        kind: string;
+    }>;
+    sensitivity: 'low' | 'normal' | 'high' | (string & {});
+    countable?: string[];
+}
+/** `GET /_capabilities`: narrowed to exactly what this token and this user may do. */
+export interface Capabilities {
+    contract: string;
+    resources: ResourceCapability[];
+    aggregations: string[];
+    operators: string[];
+    operator_symbols: string[];
+    pagination: {
+        default_size: number;
+        max_size: number;
+    } & Record<string, number>;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * The wire format of cube/api on 5.0.x, as types. Field names are the API's own (snake_case),
+ * deliberately not camelCased: a caller reading the README, `_capabilities` or a raw response in
+ * the network tab sees the same names here.
+ */
+export {};

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+/** This package's version. A test holds it equal to package.json's. */
+export declare const VERSION = "1.0.0-rc.4";
+/** The `"sdk"` value a `cube-app.json` manifest names for the API `CubeApp` offers here. */
+export declare const MANIFEST_SDK = "1";

package/dist/version.js

@@ -0,0 +1,4 @@
+/** This package's version. A test holds it equal to package.json's. */
+export const VERSION = '1.0.0-rc.4';
+/** The `"sdk"` value a `cube-app.json` manifest names for the API `CubeApp` offers here. */
+export const MANIFEST_SDK = '1';

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@cube-nl/dmp-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-rc.4",
+  "description": "Dependency-free TypeScript client for the Cube DMP REST API (cube/api), with OAuth 2.1 + PKCE, and CubeApp for no-build apps (preview on mock data, live on the DMP).",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cube-sdk.js": "./dist/cube-sdk.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build-browser.mjs",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.js",
+    "prepare": "npm run build",
+    "test:integration": "npm run build && node --test test/integration.test.js"
+  },
+  "devDependencies": {
+    "esbuild": "~0.28.2",
+    "typescript": "~5.9.3"
+  }
+}