@mapcreator/api 3.3.6 → 5.0.0-alpha.100

package/src/api/choropleth.ts

@@ -0,0 +1,228 @@
+import { type ApiError, type ApiSuccess, type Flatten, type Revivers, getSearchParams, request } from '../utils.js';
+
+import type { RequireAtLeastOne } from 'type-fest';
+import type { Polygon } from 'geojson';
+
+export const boundingBoxRevivers: Revivers<
+  { data: { bounding_box: string } } & Omit<ApiSuccess, 'data'> | ApiError,
+  { boundingBox: Polygon }
+> = {
+  boundingBox: (data: { bounding_box: string }) => JSON.parse(data.bounding_box) as Polygon,
+};
+
+export type ApiSearchPoint = {
+  lat: number;
+  lng: number;
+};
+
+export type ApiSearchBounds = {
+  min_lat: number;
+  min_lng: number;
+  max_lat: number;
+  max_lng: number;
+};
+
+type SingleOrGroupedAreaBase = {
+  id: number;
+  title: string;
+  subtitle: string;
+  svgPreview: string;
+  boundingBox: Polygon;
+};
+
+// TODO don't export this once search on click is out
+export type GroupedArea = SingleOrGroupedAreaBase & {
+  isGroup: true;
+};
+
+// TODO don't export this once search on click is out
+export type SingleArea = SingleOrGroupedAreaBase & {
+  isGroup: false;
+  properties: Record<string, string>;
+  vectorSource: string;
+  sourceLayer: string;
+  featureId: number;
+};
+
+export type SingleOrGroupedArea = {
+  id: number;
+  title: string;
+  subtitle: string;
+  svgPreview: string;
+  boundingBox: Polygon;
+  isGroup: boolean;
+  properties: Record<string, string> | null;
+  vectorSource: string | null;
+  sourceLayer: string | null;
+  featureId: number | null;
+};
+
+export type ApiSingleOrGroupedArea = {
+  data: {
+    id: number;
+    title: string;
+    subtitle: string;
+    svg_preview: string;
+    bounding_box: string;
+    is_group: boolean;
+    properties: string | null;
+    vector_source: string | null;
+    source_layer: string | null;
+    feature_id: number | null;
+  };
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiSingleOrGroupedAreaData = Flatten<Exclude<ApiSingleOrGroupedArea, ApiError>['data']>;
+
+export const singleOrGroupedAreaRevivers: Revivers<ApiSingleOrGroupedArea, SingleOrGroupedArea> = {
+  ...boundingBoxRevivers,
+  properties: (data: ApiSingleOrGroupedAreaData) =>
+    (data.properties != null ? JSON.parse(data.properties) as Record<string, string> : null),
+};
+
+/**
+ * TODO When SAGA search on click is implemented, remove mode and make searchBounds required
+ */
+export async function searchSingleOrGroupedAreas(
+  language: string,
+  search: RequireAtLeastOne<{
+    searchBounds?: ApiSearchBounds;
+    query?: string;
+    searchPoint?: ApiSearchPoint;
+  }>,
+  mode: 'polygon' | 'group' | 'both' = 'both',
+): Promise<SingleOrGroupedArea[]> {
+  const pathname = '/v1/choropleth/polygons/search';
+  const query = getSearchParams({
+    language,
+    ...search.searchBounds,
+    ...(search.query && { query: search.query }),
+    ...(search.searchPoint && { point: search.searchPoint }),
+    mode,
+  });
+  const path = `${pathname}?${query}`;
+  const options = { revivers: singleOrGroupedAreaRevivers };
+
+  type ApiSingleOrGroupedAreaArray = {
+    data: ApiSingleOrGroupedAreaData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiSingleOrGroupedAreaArray, SingleOrGroupedArea>(path, null, null, options);
+}
+
+export type GroupedAreaChild = {
+  id: number;
+  title: string;
+  vectorSource: string;
+  sourceLayer: string;
+  featureId: number;
+  boundingBox: Polygon;
+  properties: Record<string, string>;
+};
+
+type ApiGroupedAreaChild = {
+  data: {
+    id: number;
+    title: string;
+    vector_source: string;
+    source_layer: string;
+    feature_id: number;
+    bounding_box: string;
+    properties: string;
+  };
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiGroupedAreaChildData = Flatten<Exclude<ApiGroupedAreaChild, ApiError>['data']>;
+
+export const groupedAreaChildRevivers: Revivers<ApiGroupedAreaChild, GroupedAreaChild> = {
+  ...boundingBoxRevivers,
+  properties: (data: ApiGroupedAreaChildData) => JSON.parse(data.properties) as Record<string, string>,
+};
+
+export async function groupedAreaChildren(groupId: number, language: string): Promise<GroupedAreaChild[]> {
+  const pathname = `/v1/choropleth/groups/${groupId}/children-optimized`;
+  const query = getSearchParams({ language });
+  const path = `${pathname}?${query}`;
+  const options = { revivers: groupedAreaChildRevivers };
+
+  type ApiGroupedAreaChildArray = {
+    data: ApiGroupedAreaChildData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiGroupedAreaChildArray, GroupedAreaChild>(path, null, null, options);
+}
+
+export type MatchedGroup = {
+  id: number;
+  sml: number;
+  childrenCount: number;
+  matchField: string;
+  boundingBox: Polygon;
+  property: string;
+  name: string;
+};
+
+export type ApiMatchedGroup = {
+  data: {
+    id: number;
+    sml: number;
+    children_count: number;
+    match_field: string;
+    bounding_box: string;
+    property: string;
+    name: string;
+  };
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiMatchedGroupData = Flatten<Exclude<ApiMatchedGroup, ApiError>['data']>;
+
+export async function getGroupsByDataSample(
+  sample: Record<string, string[]>,
+  language: string,
+  rowCount: number,
+): Promise<MatchedGroup[]> {
+  const path = `/v1/choropleth/groups/sample`;
+  const options = { revivers: boundingBoxRevivers };
+
+  type ApiMatchedGroupArray = {
+    data: ApiMatchedGroupData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiMatchedGroupArray, MatchedGroup>(path, { sample, language, row_count: rowCount }, null, options);
+}
+
+export type BoundPolygon = {
+  index: number;
+  inputName: string;
+  id: number;
+  sml: number;
+  name: string;
+};
+
+export type ApiBoundPolygon = {
+  data: {
+    index: number;
+    input_name: string;
+    id: number;
+    sml: number;
+    name: string;
+  };
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiBoundPolygonData = Flatten<Exclude<ApiBoundPolygon, ApiError>['data']>;
+
+export async function getBoundPolygons(
+  groupId: number,
+  property: string,
+  data: string[],
+  language: string,
+): Promise<BoundPolygon[]> {
+  const path = `/v1/choropleth/groups/bind`;
+  const body = { group_id: groupId, property, data, language };
+
+  type ApiBoundPolygonArray = {
+    data: ApiBoundPolygonData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiBoundPolygonArray, BoundPolygon>(path, body);
+}

package/src/api/color.ts

@@ -0,0 +1,22 @@
+import type { ApiCommonData, ApiError, ApiSuccess, Flatten, Revivers } from '../utils.js';
+
+export type Color = {
+  id: number;
+  hex: string;
+};
+
+export type ApiColor = {
+  data: {
+    id: number;                 // The color id (sortable)
+    name: string;               // The name of the color (searchable, sortable)
+    hex: string;                // The hex value of the color (searchable, sortable)
+    order?: number;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiColorData = Flatten<Exclude<ApiColor, ApiError>['data']>;
+
+export const colorRevivers: Revivers<ApiColor, Color> = {
+  name: undefined,
+  order: undefined,
+};

package/src/api/dimension.ts

@@ -0,0 +1,44 @@
+import type { ApiCommonData, ApiError, ApiSuccess, Flatten, Revivers } from '../utils.js';
+
+export type OutputUnit =
+  | 'millimeter'
+  | 'centimeter'
+  | 'inch'
+  | 'pixel'
+  | 'pica';
+
+export type Dimension = {
+  id: number;
+  dimensionSetId: number;
+  name: string;
+  width: number;
+  height: number;
+  dpi: number;
+  unit: OutputUnit;
+};
+
+export type ApiDimension = {
+  data: {
+    id: number;                 // The dimension id (sortable)
+    dimension_set_id: number;   // The id of the dimension set
+    name: string;               // The name of dimension (searchable, sortable)
+    width: number;              // The width of the dimension (searchable, sortable)
+    height: number;             // The height of the dimension (searchable, sortable)
+    dpi: number;                // The dpi of the dimension
+    unit: string;               // The unit of this dimension
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiDimensionData = Flatten<Exclude<ApiDimension, ApiError>['data']>;
+
+const keyToUnit: { [key: string]: OutputUnit } = {
+  MM: 'millimeter',
+  CM: 'centimeter',
+  IN: 'inch',
+  PX: 'pixel',
+  PICA: 'pica',
+};
+
+export const dimensionRevivers: Revivers<ApiDimension, Dimension> = {
+  unit: (data: ApiDimensionData) => keyToUnit[data.unit],
+};

package/src/api/dimensionSet.ts

@@ -0,0 +1,20 @@
+import type { ApiCommonData, ApiError, ApiSuccess, Flatten, Revivers } from '../utils.js';
+
+export type DimensionSet = {
+  id: number;
+  name: string;
+};
+
+export type ApiDimensionSet = {
+  data: {
+    id: number;                 // The dimension set id (sortable)
+    name: string;               // The dimension set name (searchable, sortable)
+    order?: number;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiDimensionSetData = Flatten<Exclude<ApiDimensionSet, ApiError>['data']>;
+
+export const dimensionSetRevivers: Revivers<ApiDimensionSet, DimensionSet> = {
+  order: undefined,
+};

package/src/api/feature.ts

@@ -0,0 +1,22 @@
+import type { ApiCommonData, ApiError, ApiSuccess, Flatten, Revivers } from '../utils.js';
+
+export type Feature = {
+  id: number;
+  name: string;
+};
+
+export type ApiFeature = {
+  data: {
+    id: number;                 // The feature id
+    name: string;               // The feature name (searchable, sortable)
+    description: string;        // The description of the feature (searchable, sortable)
+    order?: number;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiFeatureData = Flatten<Exclude<ApiFeature, ApiError>['data']>;
+
+export const featureRevivers: Revivers<ApiFeature, Feature> = {
+  description: undefined,
+  order: undefined,
+};

package/src/api/font.ts

@@ -0,0 +1,57 @@
+import {
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  type Revivers,
+  getSearchParams,
+  request,
+} from '../utils.js';
+
+export type Font = {
+  id: number;
+  fontFamilyId: number;
+  name: string;
+  label: string;
+  weight: number;
+  style: string;
+  stretch: string;
+};
+
+export type ApiFont = {
+  data: {
+    id: number;                 // The id of the font (sortable)
+    font_family_id: number;     // The id of the font family
+    name: string;               // The name of the font (searchable, sortable)
+    style: string;              // The font style (searchable, sortable)
+    stretch: string;            // The font stretch (searchable, sortable)
+    weight: number;             // The font weight (searchable, sortable)
+    label: string;              // The label of the font (searchable, sortable)
+    order?: number;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiFontData = Flatten<Exclude<ApiFont, ApiError>['data']>;
+
+type FontSearchOptions = {
+  family?: string;
+  style?: string;
+  weight?: string;
+};
+
+export const fontRevivers: Revivers<ApiFont, Font> = {
+  order: undefined,
+};
+
+export async function getFonts(searchOptions: FontSearchOptions): Promise<Font[] | Font> {
+  const pathname = `/v1/fonts/search`;
+  const query = getSearchParams(searchOptions);
+
+  const path = `${pathname}?${query}`;
+
+  type ApiFontArray = {
+    data: ApiFontData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiFontArray, Font>(path);
+}

package/src/api/fontFamily.ts

@@ -0,0 +1,43 @@
+import { type ApiFontData, type Font, fontRevivers } from './font.js';
+import {
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  type Revivers,
+  defaultListHeader,
+  getSearchParams,
+  request,
+} from '../utils.js';
+
+export type FontFamily = {
+  id: number;
+  name: string;
+};
+
+export type ApiFontFamily = {
+  data: {
+    id: number;                 // The id of the font family (sortable)
+    name: string;               // The name of the font family (searchable, sortable)
+    order?: number;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiFontFamilyData = Flatten<Exclude<ApiFontFamily, ApiError>['data']>;
+
+export const fontFamilyRevivers: Revivers<ApiFontFamily, FontFamily> = {
+  order: undefined,
+};
+
+export async function listFontFamilyFonts(fontFamilyId: number): Promise<Font[]> {
+  const pathname = `/v1/fonts/families/${fontFamilyId}/items`;
+  const query = getSearchParams({ sort: 'order' });
+  const path = `${pathname}?${query}`;
+  const options = { revivers: fontRevivers };
+
+  type ApiFontArray = {
+    data: ApiFontData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiFontArray, Font>(path, null, defaultListHeader, options);
+}

package/src/api/geocode.ts

@@ -0,0 +1,17 @@
+import { type ApiError, type ApiSuccess, request } from '../utils.js';
+
+export type GeocodeResult = {
+  index: number;
+  lat: number | undefined;
+  lng: number | undefined;
+};
+
+export async function bulkGeocode(addresses: Array<{ index: number; address: string }>): Promise<GeocodeResult[]> {
+  const pathname = `/v1/geocode`;
+
+  type GeocodeResultArray = {
+    data: GeocodeResult[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<GeocodeResultArray, GeocodeResult>(pathname, { items: addresses });
+}

package/src/api/highlight.ts

@@ -0,0 +1,87 @@
+import type { FeatureCollection } from 'geojson';
+import type { SnakeCase } from 'type-fest';
+import {
+  APIMeta,
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  defaultListHeader,
+  getSearchParams,
+  request,
+} from '../utils.js';
+
+type FieldName = 'id' | 'name' | 'description' | 'previewPath' | 'previewJson';
+
+export type PartialVectorHighlight = Pick<VectorHighlight, FieldName>;
+
+export type VectorHighlight = {
+  id: number;
+  name: string;
+  description: string;
+  previewPath: string | null;
+  previewJson: FeatureCollection | null;
+
+  vectorSetUrl: string;
+  sourceLayerName: string;
+
+  lngMin: number;
+  lngMax: number;
+  latMin: number;
+  latMax: number;
+
+  keys: string[];
+  properties: Record<string, unknown>;
+};
+
+export type ApiVectorHighlight = {
+  data: {
+    id: number;
+    name: string;
+    description: string;
+    preview_path: string | null;
+    preview_json: FeatureCollection | null;
+
+    vector_set_url: string;
+    source_layer_name: string;
+
+    lng_min: number;
+    lng_max: number;
+    lat_min: number;
+    lat_max: number;
+
+    keys: string[];
+    properties: Record<string, unknown>;
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiVectorHighlightData = Flatten<Exclude<ApiVectorHighlight, ApiError>['data']>;
+
+export async function listVectorHighlights(name: string): Promise<PartialVectorHighlight[]> {
+  const pathname = `/v1/highlights/vector`;
+  const query = getSearchParams({ search: { name } });
+  const path = `${pathname}?${query}`;
+
+  // Only request first 50 results
+  const headers = { ...defaultListHeader };
+  const options = { withMeta: true };
+
+  type ApiVectorHighlightArray = {
+    data: Array<Pick<ApiVectorHighlightData, SnakeCase<FieldName>>>;
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiVectorHighlightArray, PartialVectorHighlight>(path, null, headers, options)
+    .catch((error: Error) => {
+      if (error instanceof APIMeta) {
+        return (error as APIMeta<ApiVectorHighlightArray, PartialVectorHighlight>).data;
+      }
+
+      throw error;
+    });
+}
+
+export async function getVectorHighlight(highlightId: number): Promise<VectorHighlight> {
+  const path = `/v1/highlights/vector/${highlightId}`;
+
+  return request<ApiVectorHighlight, VectorHighlight>(path);
+}

package/src/api/insetMap.ts

@@ -0,0 +1,95 @@
+import { apiHost, authenticate, getAuthorizationHeaders, token } from '../oauth.js';
+import {
+  APIError,
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  HTTPError,
+  NetworkError,
+  request,
+} from '../utils.js';
+
+export type InsetMap = {
+  id: number;
+  description: string;
+  jsonFilename: string;
+  latMin: number;
+  lngMin: number;
+  latMax: number;
+  lngMax: number;
+};
+
+export type ApiInsetMap = {
+  data: {
+    id: number;
+    description: string;
+    json_filename: string;
+    lat_min: number;
+    lng_min: number;
+    lat_max: number;
+    lng_max: number;
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiInsetMapData = Flatten<Exclude<ApiInsetMap, ApiError>['data']>;
+
+type Boundary = {
+  topLeft: {
+    lat: number;
+    lng: number;
+  };
+  bottomRight: {
+    lat: number;
+    lng: number;
+  };
+};
+
+export async function listInsetMaps(boundary: Boundary): Promise<InsetMap[]> {
+  const path = `/v1/inset-maps/for-boundary`;
+
+  type ApiInsetMapArray = {
+    data: ApiInsetMapData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiInsetMapArray, InsetMap>(path, { boundary });
+}
+
+export async function getInsetMap(insetMapId: number): Promise<InsetMap> {
+  const path = `/v1/inset-maps/${insetMapId}`;
+
+  return request<ApiInsetMap, InsetMap>(path);
+}
+
+export async function getInsetMapTopoJson<TopoJSON>(insetMapId: number): Promise<TopoJSON> {
+  const href = `${apiHost}/v1/inset-maps/${insetMapId}/json`;
+  const headers = getAuthorizationHeaders('GET');
+  const response = await fetch(href, { headers, ...!token && { credentials: 'include' } })
+    .catch((error: Error) => { throw new NetworkError(error?.message ?? error) });
+
+  if (response.ok) {
+    return response.json().catch(() => {
+      throw new APIError({
+        success: false,
+        error: { type: 'SyntaxError', message: 'Malformed JSON response' },
+      });
+    }) as Promise<TopoJSON>;
+  } else {
+    // eslint-disable-next-line default-case
+    switch (response.status) {
+      case 401:
+        await authenticate();
+        break; // NO-OP
+      case 403:
+      case 404:
+      case 406:
+      case 429:
+        throw new APIError({
+          success: false,
+          error: { type: 'HttpException', message: response.statusText },
+        });
+    }
+
+    throw new HTTPError(response);
+  }
+}