@carto/api-client 0.0.1-0

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@carto/api-client",
+  "version": "0.0.1-0",
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "packageManager": "yarn@4.2.2",
+  "author": "Don McCurdy <donmccurdy@carto.com>",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "source": "src/index.ts",
+  "types": "./build/index.d.ts",
+  "main": "./build/api-client.cjs",
+  "module": "./build/api-client.modern.js",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "require": "./build/api-client.cjs",
+      "default": "./build/api-client.modern.js"
+    }
+  },
+  "browserslist": [
+    "defaults",
+    "not IE 11",
+    "node >= 18"
+  ],
+  "scripts": {
+    "build": "microbundle --format cjs,modern --no-compress --define VERSION=$npm_package_version",
+    "build:watch": "microbundle watch --format cjs,modern --no-compress --define VERSION=$npm_package_version",
+    "dev": "concurrently \"yarn build:watch\" \"vite --config examples/vite.config.ts --open\"",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest watch --typecheck",
+    "coverage": "vitest run --coverage",
+    "lint": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --check",
+    "format": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --write",
+    "clean": "rimraf build/*",
+    "version": "git add -u",
+    "prepack": "yarn clean && yarn build",
+    "prepublish": "yarn lint && yarn test",
+    "postpublish": "git push && git push --tags"
+  },
+  "files": [
+    "build",
+    "src",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@deck.gl/aggregation-layers": "^9.0.14",
+    "@deck.gl/carto": "^9.0.14",
+    "@deck.gl/core": "^9.0.14",
+    "@deck.gl/extensions": "^9.0.14",
+    "@deck.gl/geo-layers": "^9.0.14",
+    "@deck.gl/layers": "^9.0.12",
+    "@deck.gl/mesh-layers": "^9.0.12",
+    "@deck.gl/react": "^9.0.17",
+    "@lit/react": "^1.0.5",
+    "@lit/task": "^1.0.1",
+    "@loaders.gl/core": "^4.2.1",
+    "@luma.gl/core": "^9.0.12",
+    "@luma.gl/engine": "^9.0.12",
+    "@sveltejs/vite-plugin-svelte": "^3.1.1",
+    "@types/json-schema": "^7.0.15",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@types/semver": "^7.5.8",
+    "@vitejs/plugin-vue": "^5.0.5",
+    "@vitest/coverage-istanbul": "^1.6.0",
+    "@webcomponents/webcomponentsjs": "^2.8.0",
+    "concurrently": "^8.2.2",
+    "echarts": "^5.5.0",
+    "lit": "^3.1.4",
+    "lit-analyzer": "^1.2.1",
+    "maplibre-gl": "^4.1.3",
+    "microbundle": "^0.15.1",
+    "prettier": "^2.6.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-map-gl": "^7.1.7",
+    "rimraf": "^3.0.2",
+    "svelte": "^4.2.17",
+    "typescript": "~5.3.3",
+    "vite": "^5.2.10",
+    "vitest": "1.6.0",
+    "vue": "^3.4.27"
+  },
+  "stableVersion": "0.0.0"
+}

package/src/client.ts

@@ -0,0 +1,17 @@
+import {CLIENT_ID} from './constants.js';
+
+/**
+ * Default client
+ * @internalRemarks Source: @carto/react-core
+ */
+let client = CLIENT_ID;
+
+/** @internalRemarks Source: @carto/react-core */
+export function getClient() {
+  return client;
+}
+
+/** @internalRemarks Source: @carto/react-core */
+export function setClient(c: string) {
+  client = c;
+}

package/src/constants-internal.ts

@@ -0,0 +1,24 @@
+/**
+ * Threshold to use GET requests, vs POST
+ * @internalRemarks Source: @carto/constants
+ * @internal
+ */
+export const REQUEST_GET_MAX_URL_LENGTH = 2048;
+
+/**
+ * @internalRemarks Source: @carto/constants
+ * @internal
+ */
+export const DEFAULT_API_BASE_URL = 'https://gcp-us-east1.api.carto.com';
+
+/**
+ * @internalRemarks Source: @carto/constants
+ * @internal
+ */
+export const DEFAULT_CLIENT = 'deck-gl-carto';
+
+/**
+ * @internalRemarks Source: @carto/react-api
+ * @internal
+ */
+export const DEFAULT_GEO_COLUMN = 'geom';

package/src/constants.ts

@@ -0,0 +1,37 @@
+export const CLIENT_ID = 'carto-api-client';
+
+/** @internalRemarks Source: @carto/constants */
+export enum MapType {
+  TABLE = 'table',
+  QUERY = 'query',
+  TILESET = 'tileset',
+}
+
+/** @internalRemarks Source: @carto/constants */
+export enum ApiVersion {
+  V1 = 'v1',
+  V2 = 'v2',
+  V3 = 'v3',
+}
+
+/** @internalRemarks Source: @carto/react-core */
+export enum GroupDateType {
+  YEARS = 'year',
+  MONTHS = 'month',
+  WEEKS = 'week',
+  DAYS = 'day',
+  HOURS = 'hour',
+  MINUTES = 'minute',
+  SECONDS = 'second',
+}
+
+/** @internalRemarks Source: @carto/react-api, @deck.gl/carto */
+export enum FilterType {
+  IN = 'in',
+  /** [a, b] both are included. */
+  BETWEEN = 'between',
+  /** [a, b) a is included, b is not. */
+  CLOSED_OPEN = 'closed_open',
+  TIME = 'time',
+  STRING_SEARCH = 'stringSearch',
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './client.js';
+export * from './constants.js';
+export * from './models/index.js';
+export * from './sources/index.js';
+export * from './types.js';

package/src/models/common.ts

@@ -0,0 +1,93 @@
+import {$TODO} from '../types-internal.js';
+import {Credentials} from '../types.js';
+import {InvalidColumnError} from '../utils.js';
+
+/** @internalRemarks Source: @carto/react-api */
+export interface ModelRequestOptions {
+  method: 'GET' | 'POST';
+  abortController?: AbortController;
+  otherOptions?: Record<string, unknown>;
+  body?: string;
+}
+
+/**
+ * Return more descriptive error from API
+ * @internalRemarks Source: @carto/react-api
+ */
+export function dealWithApiError({
+  response,
+  data,
+}: {
+  response: Response;
+  data: $TODO;
+}) {
+  if (data.error === 'Column not found') {
+    throw new InvalidColumnError(`${data.error} ${data.column_name}`);
+  }
+
+  if (data.error?.includes('Missing columns')) {
+    throw new InvalidColumnError(data.error);
+  }
+
+  switch (response.status) {
+    case 401:
+      throw new Error('Unauthorized access. Invalid credentials');
+    case 403:
+      throw new Error('Forbidden access to the requested data');
+    default:
+      const msg =
+        data && data.error && typeof data.error === 'string'
+          ? data.error
+          : JSON.stringify(data?.hint || data.error?.[0]);
+      throw new Error(msg);
+  }
+}
+
+/** @internalRemarks Source: @carto/react-api */
+export function checkCredentials(credentials: Credentials) {
+  if (!credentials || !credentials.apiBaseUrl || !credentials.accessToken) {
+    throw new Error('Missing or bad credentials provided');
+  }
+}
+
+/** @internalRemarks Source: @carto/react-api */
+export async function makeCall({
+  url,
+  credentials,
+  opts,
+}: {
+  url: string;
+  credentials: Credentials;
+  opts: ModelRequestOptions;
+}) {
+  let response;
+  let data;
+  const isPost = opts?.method === 'POST';
+  try {
+    response = await fetch(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${credentials.accessToken}`,
+        ...(isPost ? {'Content-Type': 'application/json'} : {}),
+      },
+      ...(isPost
+        ? {
+            method: opts?.method,
+            body: opts?.body,
+          }
+        : {}),
+      signal: opts?.abortController?.signal,
+      ...opts?.otherOptions,
+    });
+    data = await response.json();
+  } catch (error) {
+    if ((error as Error).name === 'AbortError') throw error;
+
+    throw new Error(`Failed request: ${error}`);
+  }
+
+  if (!response.ok) {
+    dealWithApiError({response, data});
+  }
+
+  return data;
+}

package/src/models/index.ts

@@ -0,0 +1,3 @@
+export {executeModel} from './model.js';
+export type {Model} from './model.js';
+export type {ModelRequestOptions} from './common.js';

package/src/models/model.ts

@@ -0,0 +1,112 @@
+import {getClient} from '../client';
+import {ApiVersion, MapType} from '../constants';
+import {
+  DEFAULT_GEO_COLUMN,
+  REQUEST_GET_MAX_URL_LENGTH,
+} from '../constants-internal';
+import {Source, SpatialFilter} from '../types';
+import {$TODO} from '../types-internal';
+import {assert} from '../utils';
+import {ModelRequestOptions, checkCredentials, makeCall} from './common';
+
+/** @internalRemarks Source: @carto/react-api */
+const AVAILABLE_MODELS = [
+  'category',
+  'histogram',
+  'formula',
+  'timeseries',
+  'range',
+  'scatterplot',
+  'table',
+] as const;
+
+export type Model = (typeof AVAILABLE_MODELS)[number];
+
+/**
+ * Execute a SQL model request.
+ * @internalRemarks Source: @carto/react-api
+ */
+export function executeModel(props: {
+  model: Model;
+  source: Source;
+  params: Record<string, unknown>;
+  spatialFilter?: SpatialFilter;
+  opts?: Partial<ModelRequestOptions>;
+}) {
+  assert(props.source, 'executeModel: missing source');
+  assert(props.model, 'executeModel: missing model');
+  assert(props.params, 'executeModel: missing params');
+
+  assert(
+    AVAILABLE_MODELS.indexOf(props.model) !== -1,
+    `executeModel: model provided isn't valid. Available models: ${AVAILABLE_MODELS.join(
+      ', '
+    )}`
+  );
+
+  const {source, model, params, spatialFilter, opts} = props;
+
+  checkCredentials(source.credentials);
+
+  assert(
+    source.credentials.apiVersion === ApiVersion.V3,
+    'SQL Model API is a feature only available in CARTO 3.'
+  );
+  assert(
+    source.type !== MapType.TILESET,
+    'executeModel: Tileset not supported'
+  );
+
+  let url = `${source.credentials.apiBaseUrl}/v3/sql/${source.connection}/model/${model}`;
+
+  const {filters, filtersLogicalOperator = 'and', data, type} = source;
+  const queryParameters = source.queryParameters
+    ? JSON.stringify(source.queryParameters)
+    : '';
+
+  const queryParams: Record<string, string> = {
+    type,
+    client: getClient(),
+    source: data,
+    params: JSON.stringify(params),
+    queryParameters,
+    filters: JSON.stringify(filters),
+    filtersLogicalOperator,
+  };
+
+  // API supports multiple filters, we apply it only to geoColumn
+  const spatialFilters = spatialFilter
+    ? {
+        [source.geoColumn ? source.geoColumn : DEFAULT_GEO_COLUMN]:
+          spatialFilter,
+      }
+    : undefined;
+
+  if (spatialFilters) {
+    queryParams.spatialFilters = JSON.stringify(spatialFilters);
+  }
+
+  const urlWithSearchParams =
+    url + '?' + new URLSearchParams(queryParams).toString();
+  const isGet = urlWithSearchParams.length <= REQUEST_GET_MAX_URL_LENGTH;
+  if (isGet) {
+    url = urlWithSearchParams;
+  } else {
+    // undo the JSON.stringify, @TODO find a better pattern
+    queryParams.params = params as $TODO;
+    queryParams.filters = filters as $TODO;
+    queryParams.queryParameters = source.queryParameters as $TODO;
+    if (spatialFilters) {
+      queryParams.spatialFilters = spatialFilters as $TODO;
+    }
+  }
+  return makeCall({
+    url,
+    credentials: source.credentials,
+    opts: {
+      ...opts,
+      method: isGet ? 'GET' : 'POST',
+      ...(!isGet && {body: JSON.stringify(queryParams)}),
+    },
+  });
+}

package/src/sources/index.ts

@@ -0,0 +1,5 @@
+export * from './widget-base-source.js';
+export * from './widget-query-source.js';
+export * from './widget-table-source.js';
+export * from './wrappers.js';
+export * from './types.js';

package/src/sources/types.ts

@@ -0,0 +1,90 @@
+import {
+  AggregationType,
+  SortColumnType,
+  SortDirection,
+  SpatialFilter,
+} from '../types';
+
+/******************************************************************************
+ * WIDGET API REQUESTS
+ */
+
+interface BaseRequestOptions {
+  spatialFilter?: SpatialFilter;
+  abortController?: AbortController;
+  filterOwner?: string;
+}
+
+export interface FormulaRequestOptions extends BaseRequestOptions {
+  column: string;
+  operation?: AggregationType;
+  operationExp?: string;
+}
+
+export interface CategoryRequestOptions extends BaseRequestOptions {
+  column: string;
+  operation?: AggregationType;
+  operationColumn?: string;
+}
+
+export interface RangeRequestOptions extends BaseRequestOptions {
+  column: string;
+}
+
+export interface TableRequestOptions extends BaseRequestOptions {
+  columns: string[];
+  sortBy?: string;
+  sortDirection?: SortDirection;
+  sortByColumnType?: SortColumnType;
+  page?: number;
+  rowsPerPage?: number;
+}
+
+export interface ScatterRequestOptions extends BaseRequestOptions {
+  xAxisColumn: string;
+  xAxisJoinOperation?: AggregationType;
+  yAxisColumn: string;
+  yAxisJoinOperation?: AggregationType;
+}
+
+export interface TimeSeriesRequestOptions extends BaseRequestOptions {
+  column: string;
+  stepSize?: number;
+  stepMultiplier?: number;
+  operation?: AggregationType;
+  operationColumn?: string;
+  joinOperation?: AggregationType;
+  splitByCategory?: string;
+  splitByCategoryLimit?: number;
+  splitByCategoryValues?: string[];
+}
+
+export interface HistogramRequestOptions extends BaseRequestOptions {
+  column: string;
+  ticks: number[];
+  operation?: AggregationType;
+}
+
+/******************************************************************************
+ * WIDGET API RESPONSES
+ */
+
+export type FormulaResponse = {value: number};
+
+export type CategoryResponse = {name: string; value: number}[];
+
+export type RangeResponse = {min: number; max: number};
+
+export type TableResponse = {
+  totalCount: number;
+  rows: Record<string, number | string>[];
+};
+
+export type ScatterResponse = [number, number][];
+
+export type TimeSeriesResponse = {
+  rows: {name: string; value: number}[];
+  categories: string[];
+};
+
+export type HistogramResponse = number[];