@carto/api-client 0.3.0 → 0.4.0-alpha.0

package/build/api/carto-api-error.d.ts

@@ -0,0 +1,18 @@
+import type { APIErrorContext } from './types';
+/**
+ *
+ * Custom error for reported errors in CARTO Maps API.
+ * Provides useful debugging information in console and context for applications.
+ *
+ */
+export declare class CartoAPIError extends Error {
+    /** Source error from server */
+    error: Error;
+    /** Context (API call & parameters) in which error occured */
+    errorContext: APIErrorContext;
+    /** Response from server */
+    response?: Response;
+    /** JSON Response from server */
+    responseJson?: any;
+    constructor(error: Error, errorContext: APIErrorContext, response?: Response, responseJson?: any);
+}

package/build/api/endpoints.d.ts

@@ -0,0 +1,22 @@
+import { MapType } from './types';
+export type V3Endpoint = 'maps' | 'stats' | 'sql';
+export declare function buildPublicMapUrl({ apiBaseUrl, cartoMapId, }: {
+    apiBaseUrl: string;
+    cartoMapId: string;
+}): string;
+export declare function buildStatsUrl({ attribute, apiBaseUrl, connectionName, source, type, }: {
+    attribute: string;
+    apiBaseUrl: string;
+    connectionName: string;
+    source: string;
+    type: MapType;
+}): string;
+export declare function buildSourceUrl({ apiBaseUrl, connectionName, endpoint, }: {
+    apiBaseUrl: string;
+    connectionName: string;
+    endpoint: MapType;
+}): string;
+export declare function buildQueryUrl({ apiBaseUrl, connectionName, }: {
+    apiBaseUrl: string;
+    connectionName: string;
+}): string;

package/build/api/index.d.ts

@@ -0,0 +1,4 @@
+export { CartoAPIError } from './carto-api-error';
+export type { APIErrorContext, Format, MapType, RequestType, QueryParameters, Basemap, MapLibreBasemap, GoogleBasemap, } from './types';
+export { query } from './query';
+export type { QueryOptions } from './query';

package/build/api/query.d.ts

@@ -0,0 +1,3 @@
+import type { SourceOptions, QuerySourceOptions, QueryResult } from '../sources/types';
+export type QueryOptions = SourceOptions & Omit<QuerySourceOptions, 'spatialDataColumn'>;
+export declare const query: (options: QueryOptions) => Promise<QueryResult>;

package/build/api/request-with-parameters.d.ts

@@ -0,0 +1,8 @@
+import type { APIErrorContext } from './types';
+export declare function requestWithParameters<T = any>({ baseUrl, parameters, headers: customHeaders, errorContext, maxLengthURL, }: {
+    baseUrl: string;
+    parameters?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    errorContext: APIErrorContext;
+    maxLengthURL?: number;
+}): Promise<T>;

package/build/api/types.d.ts

@@ -0,0 +1,227 @@
+export type Format = 'json' | 'geojson' | 'tilejson';
+export type MapType = 'boundary' | 'query' | 'table' | 'tileset' | 'raster';
+export type RequestType = 'Map data' | 'Map instantiation' | 'Public map' | 'Tile stats' | 'SQL' | 'Basemap style';
+export type ScaleType = 'linear' | 'ordinal' | 'log' | 'point' | 'quantile' | 'quantize' | 'sqrt' | 'custom' | 'identity';
+export type APIErrorContext = {
+    requestType: RequestType;
+    mapId?: string;
+    connection?: string;
+    source?: string;
+    type?: MapType;
+};
+export declare enum SchemaFieldType {
+    Number = "number",
+    Bigint = "bigint",
+    String = "string",
+    Geometry = "geometry",
+    Timestamp = "timestamp",
+    Object = "object",
+    Boolean = "boolean",
+    Variant = "variant",
+    Unknown = "unknown"
+}
+export interface SchemaField {
+    name: string;
+    type: SchemaFieldType;
+}
+export interface MapInstantiation extends MapInstantiationFormats {
+    nrows: number;
+    size?: number;
+    schema: SchemaField[];
+}
+type MapInstantiationFormats = Record<Format, {
+    url: string[];
+    error?: any;
+}>;
+export type QueryParameterValue = string | number | boolean | Array<QueryParameterValue> | object;
+export type NamedQueryParameter = Record<string, QueryParameterValue>;
+export type PositionalQueryParameter = QueryParameterValue[];
+export type QueryParameters = NamedQueryParameter | PositionalQueryParameter;
+export type VisualChannelField = {
+    name: string;
+    type: string;
+    colorColumn?: string;
+};
+export interface Filters {
+    [column: string]: Filter;
+}
+interface Filter {
+    [FilterTypes.In]?: number[];
+    [FilterTypes.Between]?: number[][];
+    [FilterTypes.ClosedOpen]?: number[][];
+    [FilterTypes.Time]?: number[][];
+    [FilterTypes.StringSearch]?: string[];
+}
+export declare enum FilterTypes {
+    In = "in",
+    Between = "between",// [a, b] both are included
+    ClosedOpen = "closed_open",// [a, b) a is included, b is not
+    Time = "time",
+    StringSearch = "stringSearch"
+}
+export type VisualChannels = {
+    colorField?: VisualChannelField;
+    colorScale?: ScaleType;
+    customMarkersField?: VisualChannelField;
+    customMarkersScale?: ScaleType;
+    radiusField?: VisualChannelField;
+    radiusScale?: ScaleType;
+    rotationScale?: ScaleType;
+    rotationField?: VisualChannelField;
+    sizeField?: VisualChannelField;
+    sizeScale?: ScaleType;
+    strokeColorField?: VisualChannelField;
+    strokeColorScale?: ScaleType;
+    heightField?: VisualChannelField;
+    heightScale?: ScaleType;
+    weightField?: VisualChannelField;
+};
+export type ColorRange = {
+    category: string;
+    colors: string[];
+    colorMap: string[][] | undefined;
+    name: string;
+    type: string;
+};
+export type CustomMarkersRange = {
+    markerMap: {
+        value: string;
+        markerUrl?: string;
+    }[];
+    othersMarker?: string;
+};
+export type VisConfig = {
+    filled?: boolean;
+    opacity?: number;
+    enable3d?: boolean;
+    colorAggregation?: any;
+    colorRange: ColorRange;
+    customMarkers?: boolean;
+    customMarkersRange?: CustomMarkersRange | null;
+    customMarkersUrl?: string | null;
+    radius: number;
+    radiusRange?: number[];
+    sizeAggregation?: any;
+    sizeRange?: any;
+    strokeColorAggregation?: any;
+    strokeOpacity?: number;
+    strokeColorRange?: ColorRange;
+    heightRange?: any;
+    heightAggregation?: any;
+    weightAggregation?: any;
+};
+export type TextLabel = {
+    field: VisualChannelField | null | undefined;
+    alignment?: 'center' | 'bottom' | 'top';
+    anchor?: 'middle' | 'start' | 'end';
+    size: number;
+    color?: number[];
+    offset?: [number, number];
+    outlineColor?: number[];
+};
+export type MapLayerConfig = {
+    columns?: Record<string, any>;
+    color?: number[];
+    label?: string;
+    dataId: string;
+    textLabel: TextLabel[];
+    visConfig: VisConfig;
+};
+export type MapTextSubLayerConfig = Omit<MapLayerConfig, 'textLabel'> & {
+    textLabel?: TextLabel;
+};
+export type MapConfigLayer = {
+    type: string;
+    id: string;
+    config: MapLayerConfig;
+    visualChannels: VisualChannels;
+};
+export type MapDataset = {
+    id: string;
+    data: any;
+    aggregationExp: string | null;
+    aggregationResLevel: number | null;
+    geoColumn: string;
+};
+export interface CustomStyle {
+    url?: string;
+    style?: any;
+    customAttribution?: string;
+}
+export type KeplerMapConfig = {
+    mapState: any;
+    mapStyle: {
+        styleType: string;
+        visibleLayerGroups: Record<string, boolean>;
+    };
+    visState: {
+        layers: MapConfigLayer[];
+    };
+    layerBlending: any;
+    interactionConfig: any;
+    customBaseMaps?: {
+        customStyle?: CustomStyle;
+    };
+};
+export type BasemapType = 'maplibre' | 'google-maps';
+export type Basemap = MapLibreBasemap | GoogleBasemap;
+export type BasemapCommon = {
+    /**
+     * Type of basemap.
+     */
+    type: BasemapType;
+    /**
+     * Custom attribution for style data if not provided by style definition.
+     */
+    attribution?: string;
+    /**
+     * Properties of the basemap. These properties are specific to the basemap type.
+     */
+    props: Record<string, any>;
+};
+export type MapLibreBasemap = BasemapCommon & {
+    type: 'maplibre';
+    /**
+     * MapLibre map properties.
+     *
+     * Meant to be passed to directly to `maplibregl.Map` object.
+     */
+    props: MapLibreBasemapProps;
+    /**
+     * Layer groups to be displayed in the basemap.
+     */
+    visibleLayerGroups?: Record<string, boolean>;
+    /**
+     * If `style` has been filtered by `visibleLayerGroups` then this property contains original style object, so user
+     * can use `applyLayerGroupFilters` again with new settings.
+     */
+    rawStyle?: string | Record<string, any>;
+};
+export type MapLibreBasemapProps = {
+    style: string | Record<string, any>;
+    center: [number, number];
+    zoom: number;
+    pitch?: number;
+    bearing?: number;
+};
+export type GoogleBasemap = BasemapCommon & {
+    type: 'google-maps';
+    /**
+     * Google map properties.
+     *
+     * Meant to be passed to directly to `google.maps.Map` object.
+     */
+    props: GoogleBasemapProps;
+};
+export type GoogleBasemapProps = {
+    mapTypeId: string;
+    mapId?: string;
+    center?: {
+        lat: number;
+        lng: number;
+    };
+    zoom?: number;
+    tilt?: number;
+    heading?: number;
+};
+export {};