@carto/api-client 0.5.11 → 0.5.13

package/package.json

@@ -8,7 +8,7 @@
   "homepage": "https://github.com/CartoDB/carto-api-client#readme",
   "author": "Don McCurdy <donmccurdy@carto.com>",
   "packageManager": "yarn@4.3.1",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/src/api/query.ts

@@ -13,7 +13,17 @@ import {requestWithParameters} from './request-with-parameters.js';
 import type {APIErrorContext} from './carto-api-error.js';
 import {getClient} from '../client.js';
 
-export type QueryOptions = SourceOptions & QuerySourceOptions;
+export type QueryOptions = SourceOptions &
+  QuerySourceOptions & {
+    /**
+     * @internal
+     * @experimental
+     * Used to append additional parameters to the SQL API request for features specific to providers or integrations.
+     */
+    internalParameters?: Record<string, string | boolean | number>;
+    /** Used to abort the request. */
+    signal?: AbortSignal;
+  };
 type UrlParameters = {q: string; queryParameters?: string};
 
 export const query = async function (
@@ -27,6 +37,7 @@ export const query = async function (
     connectionName,
     sqlQuery,
     queryParameters,
+    internalParameters,
   } = options;
   const urlParameters: UrlParameters = {q: sqlQuery};
 
@@ -39,7 +50,12 @@ export const query = async function (
     Authorization: `Bearer ${options.accessToken}`,
     ...options.headers,
   };
-  const parameters = {client: clientId, ...urlParameters};
+  const parameters = {
+    client: clientId,
+    ...options.tags,
+    ...internalParameters,
+    ...urlParameters,
+  };
 
   const errorContext: APIErrorContext = {
     requestType: 'SQL',
@@ -54,5 +70,6 @@ export const query = async function (
     errorContext,
     maxLengthURL,
     localCache,
+    signal: options.signal,
   });
 };

package/src/api/request-with-parameters.ts

@@ -23,6 +23,7 @@ export async function requestWithParameters<T = any>({
   errorContext,
   maxLengthURL = DEFAULT_MAX_LENGTH_URL,
   localCache,
+  signal,
 }: {
   baseUrl: string;
   parameters?: Record<string, unknown>;
@@ -30,6 +31,7 @@ export async function requestWithParameters<T = any>({
   errorContext: APIErrorContext;
   maxLengthURL?: number;
   localCache?: LocalCacheOptions;
+  signal?: AbortSignal;
 }): Promise<T> {
   // Parameters added to all requests issued with `requestWithParameters()`.
   // These parameters override parameters already in the base URL, but not
@@ -65,8 +67,9 @@ export async function requestWithParameters<T = any>({
           method: 'POST',
           body: JSON.stringify(parameters),
           headers,
+          signal,
         })
-      : fetch(url, {headers});
+      : fetch(url, {headers, signal});
 
   let response: Response | undefined;
   let responseJson: unknown;
@@ -143,10 +146,12 @@ function createURLWithParameters(
     if (isPureObject(value) || Array.isArray(value)) {
       baseUrl.searchParams.set(key, JSON.stringify(value));
     } else {
-      baseUrl.searchParams.set(
-        key,
-        (value as string | boolean | number).toString()
-      );
+      if (value !== null && value !== undefined) {
+        baseUrl.searchParams.set(
+          key,
+          (value as string | boolean | number).toString()
+        );
+      }
     }
   }
   return baseUrl.toString();

package/src/models/model.ts

@@ -43,6 +43,7 @@ export interface ModelSource {
   spatialDataColumn?: string;
   spatialDataType?: SpatialDataType;
   spatialFiltersMode?: SpatialFilterPolyfillMode;
+  tags?: Record<string, string>;
 }
 
 const {V3} = ApiVersion;
@@ -87,6 +88,7 @@ export function executeModel(props: {
     spatialDataType = 'geo',
     spatialDataColumn = DEFAULT_GEO_COLUMN,
     spatialFiltersMode = 'intersects',
+    tags,
   } = source;
 
   const queryParams: Record<string, unknown> = {
@@ -97,6 +99,7 @@ export function executeModel(props: {
     queryParameters: source.queryParameters || '',
     filters,
     filtersLogicalOperator,
+    ...(tags ?? {}),
   };
 
   queryParams.spatialDataType = spatialDataType;

package/src/sources/base-source.ts

@@ -47,7 +47,7 @@ export async function baseSource<UrlParameters extends Record<string, unknown>>(
     Authorization: `Bearer ${options.accessToken}`,
     ...options.headers,
   };
-  const parameters = {client: clientId, ...urlParameters};
+  const parameters = {client: clientId, ...options.tags, ...urlParameters};
 
   const errorContext: APIErrorContext = {
     requestType: 'Map instantiation',

package/src/sources/constants.ts

@@ -0,0 +1,8 @@
+export enum RasterBandColorinterp {
+  Gray = 'gray',
+  Red = 'red',
+  Green = 'green',
+  Blue = 'blue',
+  Alpha = 'alpha',
+  Palette = 'palette',
+}

package/src/sources/index.ts

@@ -3,6 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 export {SOURCE_DEFAULTS} from './base-source.js';
+export {RasterBandColorinterp} from './constants.js';
 export type {
   SourceOptions,
   SourceRequiredOptions,
@@ -26,7 +27,6 @@ export type {
   RasterMetadataBand,
   RasterMetadataBandStats,
   RasterBandType,
-  RasterBandColorinterp,
 } from './types.js';
 
 export {boundaryQuerySource} from './boundary-query-source.js';

package/src/sources/types.ts

@@ -3,6 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import type {Filters, SchemaField, QueryParameters} from '../types.js';
+import type {RasterBandColorinterp} from './constants.js';
 
 export type SourceRequiredOptions = {
   /** Carto platform access token. */
@@ -75,6 +76,9 @@ export type SourceOptionalOptions = {
    * By default, local in-memory caching is enabled.
    */
   localCache?: LocalCacheOptions;
+
+  /** Additional tags appended to HTTP requests, available for analytics and audits. */
+  tags?: Record<string, string>;
 };
 
 export type LocalCacheOptions = {
@@ -357,15 +361,6 @@ export type RasterMetadataBandStats = {
   version?: string;
 };
 
-export enum RasterBandColorinterp {
-  Gray = 'gray',
-  Red = 'red',
-  Green = 'green',
-  Blue = 'blue',
-  Alpha = 'alpha',
-  Palette = 'palette',
-}
-
 export type RasterBandType =
   | 'uint8'
   | 'int8'

package/src/widget-sources/widget-remote-source.ts

@@ -61,6 +61,7 @@ export abstract class WidgetRemoteSource<
       filtersLogicalOperator: props.filtersLogicalOperator,
       spatialDataType: props.spatialDataType,
       spatialDataColumn: props.spatialDataColumn,
+      tags: props.tags,
     };
   }