@mapcreator/api 0.0.0-saga.0

package/src/api/choropleth.ts

@@ -0,0 +1,105 @@
+import { type ApiError, type ApiSuccess, getSearchParams, request } from '../utils.js';
+import type { Polygon } from 'geojson';
+
+export type SearchPoint = {
+  lat: number;
+  lng: number;
+};
+
+export type SearchBounds = {
+  min_lat: number;
+  min_lng: number;
+  max_lat: number;
+  max_lng: number;
+};
+
+type ApiAreaArray =
+  | ({ data: ApiArea[] } & Omit<ApiSuccess, 'data'>)
+  | ApiError;
+
+type ApiArea = {
+  id: number;
+  title: string;
+  subtitle: string;
+  svg_preview: string;
+  bounding_box: string;
+  is_group: boolean;
+  vector_source: string | null;
+  source_layer: string | null;
+  feature_id: number | null;
+  properties: Record<string, string> | null;
+};
+
+type AreaBase = {
+  id: number;
+  title: string;
+  subtitle: string;
+  svgPreview: string;
+  boundingBox: Polygon;
+};
+
+type GroupArea = AreaBase & {
+  isGroup: true;
+};
+
+type SingleArea = AreaBase & {
+  isGroup: false;
+  vectorSource: string;
+  sourceLayer: string;
+  featureId: number;
+  properties: Record<string, string>;
+};
+
+export type Area = SingleArea | GroupArea;
+
+export async function search(
+  language: string,
+  searchBounds: SearchBounds,
+  query?: string,
+  searchPoint?: SearchPoint,
+): Promise<Area[]> {
+  return request<ApiAreaArray, Area>(
+    `/v1/choropleth/polygons/search?${getSearchParams({
+      language,
+      ...searchBounds,
+      ...(query !== '' && { query }),
+      ...(searchPoint && { point: searchPoint }),
+    })}`,
+  ).then(result => {
+    result.forEach(
+      elem => (elem.boundingBox = JSON.parse(elem.boundingBox as unknown as string) as Polygon),
+    );
+
+    return result;
+  });
+}
+
+type ApiChildArray =
+  | ({
+    data: ApiChild[];
+  } & Omit<ApiSuccess, 'data'>)
+  | ApiError;
+
+type ApiChild = {
+  id: number;
+  title: string;
+  vector_source: string;
+  source_layer: string;
+  feature_id: number;
+  properties: Record<string, string>;
+};
+
+export type AreaChild = {
+  id: number;
+  title: string;
+  vectorSource: string;
+  sourceLayer: string;
+  featureId: number;
+  properties: Record<string, string>;
+};
+
+export async function children(groupId: number, language: string): Promise<AreaChild[]> {
+  return request<ApiChildArray, AreaChild>(
+    `/v1/choropleth/groups/${groupId}/children-optimized?${getSearchParams({ language })}`,
+  );
+}

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,49 @@
+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;
+};
+
+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> = {
+  style: undefined,
+  stretch: undefined,
+  weight: undefined,
+  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/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/job.ts

@@ -0,0 +1,129 @@
+import type { ApiJobShare, JobShare, JobShareVisibility } from './jobShare.js';
+import { type JobSearchResult, listJobs } from './apiCommon.js';
+import {
+  type ApiCommon,
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  type Revivers,
+  deletedNoneParam,
+  request,
+} from '../utils.js';
+
+export type Job = {
+  id: number;
+  jobTypeId: number;
+  title: string;
+  previewPath: string | undefined;
+  createdAt: string;
+  star: boolean;
+  jobFolderId: number | null;
+  userEmail: string | undefined;
+  jobFolderName: string | null;
+  userId: number;
+};
+
+export type ApiJob = {
+  data: {
+    id: number;                 // The job id (sortable)
+    job_type_id: number;        // The id of the job type (searchable)
+    user_id: number;            // The user id (searchable)
+    title: string;              // The title of the job (searchable, sortable)
+    description: string | null; // The description of the job (searchable, sortable)
+    share_token: string | null; // The token used for sharing this job
+    autosave_preview_path: string | null; //  The preview path of the Job
+    job_folder_id: number | null; // TODO: not present in API specification!
+    job_folder_name?: string | null; // TODO: not present in API specification!
+    star: boolean;              // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiJobData = Flatten<Exclude<ApiJob, ApiError>['data']>;
+
+export const jobRevivers: Revivers<ApiJob, Job> = {
+  description: undefined,
+  share_token: undefined,
+  autosave_preview_path: undefined,
+
+  jobTypeId: () => 9,
+  jobFolderName: (data: ApiJobData) => data.job_folder_name ?? null,
+  createdAt: (data: ApiJobData) => data.created_at as string,
+  previewPath: (data: ApiJobData) => data.autosave_preview_path ?? undefined,
+};
+
+export async function createJob(title: string): Promise<Job> {
+  const path = `/v1/jobs`;
+  const body = { title, job_type_id: 9 };
+  const options = { revivers: jobRevivers };
+
+  // Technically, the returning `data` will contain only the following fields:
+  // Pick<ApiJobData, 'id' | 'job_type_id' | 'user_id' | 'title' | 'created_at' | 'updated_at'>
+
+  return request<ApiJob, Job>(path, body, null, options);
+}
+
+export async function getJob(jobId: number): Promise<Job> {
+  const path = `/v1/jobs/${jobId}`;
+  const options = { revivers: jobRevivers };
+
+  return request<ApiJob, Job>(path, null, null, options);
+}
+
+export async function deleteJob(jobId: number): Promise<Record<string, never>> {
+  const path = `/v1/jobs/${jobId}`;
+
+  return request<ApiCommon, Record<string, never>>(path, null, null, { method: 'DELETE' });
+}
+
+export async function updateJob(jobId: number, newTitle: string): Promise<Record<string, never>> {
+  const path = `/v1/jobs/${jobId}`;
+  const body = { title: newTitle };
+
+  return request<ApiCommon, Record<string, never>>(path, body, null, { method: 'PATCH' });
+}
+
+export async function updateJobFolder(jobId: number, folderId: number | null): Promise<Record<string, never>> {
+  const path = `/v1/jobs/${jobId}`;
+  const body = { job_folder_id: folderId };
+
+  return request<ApiCommon, Record<string, never>>(path, body, null, { method: 'PATCH' });
+}
+
+export async function starJob(jobId: number, star: boolean): Promise<Record<string, never>> {
+  const path = `/v1/jobs/${jobId}`;
+  const body = { star };
+
+  return request<ApiCommon, Record<string, never>>(path, body, null, { method: 'PATCH' });
+}
+
+export async function generateJobShare(
+  jobId: number,
+  visibility: JobShareVisibility,
+): Promise<JobShare> {
+  const path = `/v1/jobs/${jobId}/share`;
+  const body = { visibility };
+
+  return request<ApiJobShare, JobShare>(path, body);
+}
+
+export async function uploadJobPreview(
+  jobId: number,
+  preview: Blob,
+): Promise<Record<string, never>> {
+  const pathname = `/v1/jobs/${jobId}/preview`;
+  const path = `${pathname}?${deletedNoneParam}`;
+  const body = new FormData();
+
+  body.append('preview', preview);
+
+  return request<ApiCommon, Record<string, never>>(path, body);
+}
+
+export async function listFeaturedJobs(
+  title: string,
+  page: number,
+  options?: Record<string, unknown>,
+): Promise<JobSearchResult> {
+  return listJobs(`/v1/jobs/featured`, title, page, options);
+}

package/src/api/jobResult.ts

@@ -0,0 +1,95 @@
+import {
+  type ApiCommon,
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  type Revivers,
+  deletedNoneParam,
+  lastJobRevision,
+  request,
+} from '../utils.js';
+
+export type JobResult = {
+  jobRevisionId: number;
+  revision: number;
+  status: string;
+};
+
+export type ApiJobResult = {
+  data: {
+    job_revision_id: number;    // The id of the job revision
+    revision: number;           // The revision number of the job revision
+    mapstyle_id: number;        // The id of the map style
+    interface_version: string;  // The version of the interface (searchable, sortable)
+    fix: string;                //
+    status: string;             // The status of the job result (searchable, sortable)
+    fail_reason: string;        // A human-readable reason of why the map failed to process
+    process_start: string;      // The datetime when the job process started (searchable, sortable)
+    process_end: string;        // The datetime when the job process ended (searchable, sortable)
+    dealt_with: boolean;        // Checks if the Support fixed an issue (searchable, sortable)
+    bought: boolean;            // Checks if the result is bought or not (searchable, sortable)
+    contract_id: number;        // The id of the contract that was active when the map was created
+    callback: string;           // URL to another API which can finish a map (searchable, sortable)
+    last_downloaded: string;    // The last time the archive was downloaded (searchable, sortable)
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiJobResultData = Flatten<Exclude<ApiJobResult, ApiError>['data']>;
+
+export const jobResultRevivers: Revivers<ApiJobResult, JobResult> = {
+  mapstyle_id: undefined,
+  interface_version: undefined,
+  fix: undefined,
+  fail_reason: undefined,
+  process_start: undefined,
+  process_end: undefined,
+  dealt_with: undefined,
+  bought: undefined,
+  contract_id: undefined,
+  callback: undefined,
+  last_downloaded: undefined,
+};
+
+export async function uploadJobResultPreview(
+  jobId: number,
+  blob: Blob,
+): Promise<Record<string, never>> {
+  const pathname = `/v1/jobs/${jobId}/revisions/${lastJobRevision}/result/preview`;
+  const path = `${pathname}?${deletedNoneParam}`;
+  const body = new FormData();
+
+  body.append('preview', blob);
+
+  return request<ApiCommon, Record<string, never>>(path, body);
+}
+
+export type JobResultHostedImage = {
+  url: string;
+  message: string;
+};
+
+export type ApiJobResultHostedImage = {
+  data: {
+    url: string;
+    message: string;
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiJobResultHostedImageData = Flatten<Exclude<ApiJobResultHostedImage, ApiError>['data']>;
+
+export async function uploadJobResultHostedImage(
+  jobId: number,
+  blob: Blob,
+  fileName: string,
+  fileType: 'jpg' | 'png' | 'svg',
+): Promise<JobResultHostedImage> {
+  const pathname = `/v1/jobs/${jobId}/revisions/${lastJobRevision}/result/hosted-${fileType}`;
+  const path = `${pathname}?${deletedNoneParam}`;
+  const body = new FormData();
+
+  body.append(fileType, blob);
+  body.append('filename', fileName);
+
+  return request<ApiJobResultHostedImage, JobResultHostedImage>(path, body);
+}