@mapcreator/api 0.0.0-saga.0

package/src/api/jobRevision.ts

@@ -0,0 +1,278 @@
+import { type ApiLayerData, type Layer, layerRevivers } from './layer.js';
+import { apiHost, authenticate, token } from '../oauth.js';
+import type { ApiMapstyleSetData } from './mapstyleSet.js';
+import type { ApiLanguageData } from './language.js';
+import {
+  APIError,
+  type ApiCommon,
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  HTTPError,
+  NetworkError,
+  type Revivers,
+  defaultListHeader,
+  deletedNoneParam,
+  lastJobRevision,
+  request,
+} from '../utils.js';
+
+export type FileFormat =
+  | 'png'
+  | 'jpg'
+  | 'tiff'
+  | 'svg'
+  | 'pdf'
+  | 'web'
+  | 'web_download'
+  | 'webm'
+  | 'mp4'
+  | 'mov'
+  | 'eps'
+  | 'eps_log'
+  | 'png_sequence'
+  | 'jpg_sequence'
+  | 'mxf';
+
+export type JobRevision = {
+  id: number;
+  jobId: number;
+  revision: number;
+  languageCode: string;
+  mapstyleSetId: number;
+  output: FileFormat;
+};
+
+export type ApiJobRevision = {
+  data: {
+    id: number;                 // The id of the job revision (sortable)
+    job_id: number;             // The id of the job related to this revision (searchable, sortable)
+    revision: number;           // The revision number (searchable, sortable)
+    language_code: string;      // The language code of the revision (searchable, sortable)
+    mapstyle_set_id: number;    // The id of the mapstyle set
+    archived: boolean;          // Whether the revision has been generated (searchable, sortable)
+    output: FileFormat;         // The output file type
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiJobRevisionData = Flatten<Exclude<ApiJobRevision, ApiError>['data']>;
+
+export const jobRevisionRevivers: Revivers<ApiJobRevision, JobRevision> = {
+  archived: undefined,
+};
+
+export async function createJobRevision(
+  jobId: number,
+  languageCode: string,
+  mapstyleSetId: number,
+  layers: number[],
+  output: FileFormat,
+  jobObject: Record<string, unknown>,
+): Promise<JobRevision> {
+  const pathname = `/v1/jobs/${jobId}/revisions`;
+  const path = `${pathname}?${deletedNoneParam}`;
+  const body = {
+    language_code: languageCode,
+    mapstyle_set_id: mapstyleSetId,
+    object: JSON.stringify(jobObject),
+    output,
+    layers,
+  };
+  const options = { revivers: jobRevisionRevivers };
+
+  return request<ApiJobRevision, JobRevision>(path, body, null, options);
+}
+
+export async function getJobRevision(jobId: number): Promise<JobRevision | undefined> {
+  const path = `/v1/jobs/${jobId}/revisions/${lastJobRevision}`;
+  const options = { revivers: jobRevisionRevivers };
+
+  return request<ApiJobRevision, JobRevision>(path, null, null, options).catch(() => undefined);
+}
+
+export async function getJobRevisionObject<JobObject>(jobId: number): Promise<JobObject> {
+  const pathname = `/v1/jobs/${jobId}/revisions/${lastJobRevision}/object`;
+  const path = `${pathname}?${deletedNoneParam}`;
+
+  return request<ApiCommon, string>(path).then(JSON.parse) as Promise<JobObject>;
+}
+
+export type JobCanBuild = {
+  canBuild: boolean;
+  paymentSource: string;
+  reason: string | null;
+};
+
+export type ApiJobCanBuild = {
+  data: {
+    can_build: boolean;
+    payment_source: string;
+    reason: string | null;
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+// Also known as `canBuild()`
+export async function getJobRevisionBuild(jobId: number): Promise<JobCanBuild> {
+  const pathname = `/v1/jobs/${jobId}/revisions/${lastJobRevision}/build`;
+  const path = `${pathname}?${deletedNoneParam}`;
+
+  return request<ApiJobCanBuild, JobCanBuild>(path);
+}
+
+export type JobRevisionBuild = {
+  jobRevisionId: number;
+  revision: number;
+  status: string;
+};
+
+export type ApiJobRevisionBuild = {
+  data: {
+    job_revision_id: number;    // The id of the job revision
+    status: string;             // The status of the job result (searchable, sortable)
+    contract_id: number;        // The id of the contract that was active when the map was created
+    process_start: string;      // The datetime when the job process started (searchable, sortable)
+    process_end: string;        // The datetime when the job process ended (searchable, sortable)
+    last_downloaded: string;    // The last time the archive was downloaded (searchable, sortable)
+    bought: boolean;            // Checks if the result is bought or not (searchable, sortable)
+    revision: number;           // The revision number of the job revision
+    job_revision: ApiJobRevisionData;
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiJobRevisionBuildData = Flatten<Exclude<ApiJobRevisionBuild, ApiError>['data']>;
+
+export const jobRevisionBuildRevivers: Revivers<ApiJobRevisionBuild, JobRevisionBuild> = {
+  contract_id: undefined,
+  process_start: undefined,
+  process_end: undefined,
+  last_downloaded: undefined,
+  bought: undefined,
+  job_revision: undefined,
+};
+
+export async function registerJobRevisionBuild(
+  jobId: number,
+  status: string,
+  start: Date,
+  end: Date,
+): Promise<JobRevisionBuild> {
+  const pathname = `/v1/jobs/${jobId}/revisions/${lastJobRevision}/build/register`;
+  const path = `${pathname}?${deletedNoneParam}`;
+  const body = { status, process_start: start, process_end: end };
+  const options = { revivers: jobRevisionBuildRevivers };
+
+  return request<ApiJobRevisionBuild, JobRevisionBuild>(path, body, null, options);
+}
+
+export async function cloneJobRevision(jobId: number, newTitle?: string): Promise<JobRevision> {
+  const pathname = `/v1/jobs/${jobId}/revisions/${lastJobRevision}/clone`;
+  const path = `${pathname}?${deletedNoneParam}`;
+  const body = { title: newTitle ?? null };
+  const options = {
+    revivers: {
+      ...jobRevisionRevivers,
+      layers: undefined,
+      language: undefined,
+      mapstyle_set: undefined,
+    },
+  };
+
+  type ApiJobRevisionWithData = {
+    data: ApiJobRevisionData & {
+      layers: ApiLayerData[];
+      language: ApiLanguageData;
+      mapstyle_set: ApiMapstyleSetData;
+    };
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiJobRevisionWithData, JobRevision>(path, body, null, options);
+}
+
+export async function listJobRevisionLayers(jobId: number): Promise<Layer[]> {
+  const path = `/v1/jobs/${jobId}/revisions/${lastJobRevision}/layers`;
+  const options = { revivers: layerRevivers };
+
+  type ApiLayerArray = {
+    data: ApiLayerData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiLayerArray, Layer>(path, null, defaultListHeader, options);
+}
+
+export type JobRevisionOutputUrl = { url: string };
+
+export type ApiJobRevisionOutputUrl = {
+  data: JobRevisionOutputUrl & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export async function getJobRevisionOutputUrl(jobId: number): Promise<JobRevisionOutputUrl> {
+  await createJobRevisionBuild(jobId);
+
+  const path = `/v1/jobs/${jobId}/revisions/${lastJobRevision}/result/output-url`;
+
+  return request<ApiJobRevisionOutputUrl, JobRevisionOutputUrl>(path);
+}
+
+export type JobRevisionOutput = { blob: Blob; filename?: string | undefined };
+
+export async function getJobRevisionOutput(jobId: number): Promise<JobRevisionOutput> {
+  await createJobRevisionBuild(jobId);
+
+  const href = `${apiHost}/v1/jobs/${jobId}/revisions/${lastJobRevision}/result/output`;
+  const headers = { ...(token ? { Authorization: token.toString() } : null) };
+  const response = await fetch(href, { headers }).catch((error: Error) => {
+    throw new NetworkError(error?.message ?? error);
+  });
+
+  if (response.ok) {
+    const blob = await response.blob().catch(() => {
+      throw new APIError({ success: false, error: { type: 'TypeError', message: 'Malformed Blob response' } });
+    });
+    const contentDisposition = response.headers.get('Content-Disposition');
+
+    if (contentDisposition) {
+      const filenameRegex = /filename\*\s*=\s*UTF-8''(.+)/i;
+      const filenameMatch = contentDisposition.match(filenameRegex);
+
+      if (filenameMatch?.[1]) {
+        return { blob, filename: filenameMatch[1] };
+      }
+
+      const fallbackRegex = /filename\s*=\s*"([^"]+)"/i;
+      const fallbackMatch = contentDisposition.match(fallbackRegex);
+
+      if (fallbackMatch?.[1]) {
+        return { blob, filename: fallbackMatch[1] };
+      }
+    }
+
+    return { blob };
+  } 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(
+          (await response.json().catch(() => ({
+            success: false,
+            error: { type: 'HttpException', message: response.statusText },
+          }))) as ApiError,
+        );
+    }
+
+    throw new HTTPError(response);
+  }
+}
+
+async function createJobRevisionBuild(jobId: number): Promise<string> {
+  const pathname = `/v1/jobs/${jobId}/revisions/${lastJobRevision}/build`;
+  const path = `${pathname}?${deletedNoneParam}`;
+
+  return request<ApiCommon, string>(path, null, null, { method: 'POST' });
+}

package/src/api/jobShare.ts

@@ -0,0 +1,35 @@
+import { type ApiCommon, type ApiCommonData, type ApiError, type ApiSuccess, type Flatten, request } from '../utils.js';
+
+export type JobShareVisibility = 'private' | 'organisation' | 'public';
+
+export type JobShare = {
+  id: number;
+  jobId: number;
+  visibility: JobShareVisibility;
+  hashKey: string;
+  apiUrl: string;
+  webUrl: string;
+};
+
+export type ApiJobShare = {
+  data: {
+    id: number;                 // The id of the job share (sortable)
+    job_id: number;             // The id of the job related to this share
+    visibility: string;         // The visibility of the job share (searchable, sortable)
+    hash_key: string;           // The hash key of the job share
+    apiUrl: string;             // TODO: not present in API specification!
+    webUrl: string;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiJobShareData = Flatten<Exclude<ApiJobShare, ApiError>['data']>;
+
+export type ApiJobShareArray = {
+  data: ApiJobShareData[];
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export async function deleteJobShare(jobShareId: number): Promise<Record<string, never>> {
+  const path = `/v1/jobs/shares/${jobShareId}`;
+
+  return request<ApiCommon, Record<string, never>>(path, null, null, { method: 'DELETE' });
+}

package/src/api/jobType.ts

@@ -0,0 +1,26 @@
+import type { ApiCommonData, ApiError, ApiSuccess, Flatten, Revivers } from '../utils.js';
+
+export type JobType = {
+  id: number;
+};
+
+export type ApiJobType = {
+  data: {
+    id: number;                 // The id of the job type (sortable)
+    name: string;               // The name of the job type (searchable, sortable)
+    preview: string | null;     // The preview file name of the job type
+    description: string | null; // The description of the job type (searchable, sortable)
+    components: string | null;  // The components of the job type
+    order?: number;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiJobTypeData = Flatten<Exclude<ApiJobType, ApiError>['data']>;
+
+export const jobTypeRevivers: Revivers<ApiJobType, JobType> = {
+  name: undefined,
+  preview: undefined,
+  description: undefined,
+  components: undefined,
+  order: undefined,
+};

package/src/api/language.ts

@@ -0,0 +1,19 @@
+import type { ApiCommonData, ApiError, ApiSuccess, Flatten } from '../utils.js';
+
+export type Language = {
+  code: string;
+  name: string;
+  locale: string;
+  interface: boolean;
+};
+
+export type ApiLanguage = {
+  data: {
+    code: string;               // The language code
+    name: string;               // The name of the language (searchable, sortable)
+    locale: string;             // The locale string for the language (searchable, sortable)
+    interface: boolean;         // If this language can be used for user interfaces
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiLanguageData = Flatten<Exclude<ApiLanguage, ApiError>['data']>;

package/src/api/layer.ts

@@ -0,0 +1,38 @@
+import type { ApiCommonData, ApiError, ApiSuccess, Flatten, Revivers } from '../utils.js';
+
+export type Layer = {
+  id: number;
+  name: string;
+  description: string;
+  svg: string | null;
+};
+
+export type ApiLayer = {
+  data: {
+    id: number;                 // The id of the layer (sortable)
+    name: string;               // The name of the layer (searchable, sortable)
+    path: string;               // The path to the layer
+    description: string;        // The description of the layer (searchable, sortable)
+    image: string | null;       // The image related to a layer
+    svg: string | null;         // The svg related to a layer
+    scale_min: number;          // The minimum scale for the layer (searchable, sortable)
+    scale_max: number;          // The maximum scale for the layer (searchable, sortable)
+    pangaea_ready: boolean;     // Whether a layer is prepared for Pangaea (searchable, sortable)
+    svg_set_id: number | null;  // TODO: not present in API specification!
+    pivot: unknown;             // TODO: not present in API specification!
+    order?: number;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiLayerData = Flatten<Exclude<ApiLayer, ApiError>['data']>;
+
+export const layerRevivers: Revivers<ApiLayer, Layer> = {
+  path: undefined,
+  image: undefined,
+  scale_min: undefined,
+  scale_max: undefined,
+  pangaea_ready: undefined,
+  svg_set_id: undefined,
+  pivot: undefined,
+  order: undefined,
+};

package/src/api/layerFaq.ts

@@ -0,0 +1,53 @@
+import {
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  type Revivers,
+  defaultListHeader,
+  getSearchParams,
+  request,
+} from '../utils.js';
+
+export type LayerFaq = {
+  id: number;
+  name: string;
+  description: string;
+  mediaUrl: string;
+  readMoreUrl: string;
+  tags: string[];
+  layerId: number;
+  order?: number;
+};
+
+export type ApiLayerFaq = {
+  data: {
+    id: number;                 // The id of the layer faq (sortable)
+    name: string;               // The name of this layer faq (searchable, sortable)
+    description: string;        // The description of the layer faq (searchable)
+    media_url: string;          // The image for the faq (searchable)
+    read_more_url: string;      // A link to a page with more information (searchable)
+    tags: string[];             // A list of tags to search in (searchable)
+    layer_id: number;           // TODO: not present in API specification!
+    order?: number;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiLayerFaqData = Flatten<Exclude<ApiLayerFaq, ApiError>['data']>;
+
+export const layerFaqRevivers: Revivers<ApiLayerFaq, LayerFaq> = {
+  order: undefined,
+};
+
+export async function listLayerFaqs(): Promise<LayerFaq[]> {
+  const pathname = `/v1/layer-faqs`;
+  const query = getSearchParams({ sort: 'order,name' });
+  const path = `${pathname}?${query}`;
+  const options = { revivers: layerFaqRevivers };
+
+  type ApiLayerFaqArray = {
+    data: ApiLayerFaqData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiLayerFaqArray, LayerFaq>(path, null, defaultListHeader, options);
+}

package/src/api/layerGroup.ts

@@ -0,0 +1,69 @@
+import type { Layer } from './layer.js';
+import {
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  getSearchParams,
+  request,
+} from '../utils.js';
+
+export type LayerGroup = {
+  id: number;
+  name: string;
+  layers: Layer[];
+};
+
+export type ApiLayerGroup = {
+  data: {
+    id: number;                 // The id of the layer group (sortable)
+    name: string;               // The name of the layer group (searchable, sortable)
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiLayerGroupData = Flatten<Exclude<ApiLayerGroup, ApiError>['data']>;
+
+export async function listLayerGroups(layers: Layer[]): Promise<LayerGroup[]> {
+  const pathname = `/v1/layer-groups/for-layer-ids`;
+  const query = getSearchParams({ layer_ids: layers.map(layer => layer.id) });
+  const path = `${pathname}?${query}`;
+
+  type ApiLayerGroupArray = {
+    data: Array<ApiLayerGroupData & { layers: Array<{ id: number }> }>;
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  const layerGroups = await request<ApiLayerGroupArray, LayerGroup>(path);
+
+  // Arrange layers in an object by id for fast lookups
+  const layerMap = new Map(layers.map(layer => [layer.id, layer]));
+
+  // Create a set of all layer ids that belong to a group
+  const groupedLayerIds = new Set<number>();
+
+  for (const layerGroup of layerGroups) {
+    // Replace layers from the API response with their full representation
+    layerGroup.layers = layerGroup.layers
+      .map(groupLayer => layerMap.get(groupLayer.id))
+      .filter((layer): layer is Layer => layer !== undefined);
+
+    // Remember that these layers belong to a group
+    for (const layer of layerGroup.layers) {
+      groupedLayerIds.add(layer.id);
+    }
+  }
+
+  // Get a list of layers that don’t belong to any group
+  const miscLayers = layers.filter(layer => !groupedLayerIds.has(layer.id));
+
+  // Sort it alphabetically
+  miscLayers.sort((a, b) => a.name.localeCompare(b.name));
+
+  // Put them all in a separate group
+  const miscLayerGroup: LayerGroup = {
+    id: 999,
+    layers: miscLayers,
+    name: 'Other layers',
+  };
+
+  return [...layerGroups, miscLayerGroup];
+}

package/src/api/mapstyleSet.ts

@@ -0,0 +1,48 @@
+import type { ApiCommonData, ApiError, ApiSuccess, Flatten, Revivers } from '../utils.js';
+
+export type MapstyleSet = {
+  id: number;
+  name: string;
+  supportsSvg: boolean;
+  disableInteractive: boolean;
+};
+
+export type ApiMapstyleSet = {
+  data: {
+    id: number;                 // The id of the mapstyle set (sortable)
+    name: string;               // The name of the mapstyle set (searchable, sortable)
+    description: string;        // The description of the set (searchable, sortable)
+    supports_svg: boolean;      // If the set supports svg (searchable, sortable)
+    disable_interactive: boolean; // If interactive export is disabled
+    job_type_id: number;        // The id of the job type (searchable)
+    preview_lat: number;        // The latitude for the preview image
+    preview_lon: number;        // The longitude for the preview image
+    preview_language_code: string; // The language code of the preview
+    world_cache: string | null; // The name of the world cache (sortable)
+    world_cache_max_zoom: number | null; // The max zoom level of the world cache (sortable)
+    css: string | null;         // Custom CSS for the MapstyleSet (sortable)
+    locator_ready: boolean;     // If the set can be used as locator (searchable, sortable)
+    show_underlying_elements: boolean; // Shows elements even if behind annotations
+    ace_on_osm: boolean;        // Use OSM source as data for ACE maps (searchable, sortable)
+    order?: number;             // TODO: not present in API specification!
+    custom_settings?: string | null; // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiMapstyleSetData = Flatten<Exclude<ApiMapstyleSet, ApiError>['data']>;
+
+export const mapstyleSetRevivers: Revivers<ApiMapstyleSet, MapstyleSet> = {
+  description: undefined,
+  job_type_id: undefined,
+  preview_lat: undefined,
+  preview_lon: undefined,
+  preview_language_code: undefined,
+  world_cache: undefined,
+  world_cache_max_zoom: undefined,
+  css: undefined,
+  locator_ready: undefined,
+  show_underlying_elements: undefined,
+  ace_on_osm: undefined,
+  order: undefined,
+  custom_settings: undefined,
+};

package/src/api/message.ts

@@ -0,0 +1,80 @@
+import {
+  type ApiCommon,
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  type Revivers,
+  request,
+} from '../utils.js';
+
+export type Message = {
+  index: number;
+  image: string;
+  date: string;
+  read: boolean;
+  type: 'New feature' | 'Announcement';
+  video: boolean;
+  title: string;
+  text: string;
+};
+
+type ApiMessageVariant = {
+  language_code: string;
+  content: string;
+  title: string;
+} & ApiCommonData;
+
+export type ApiMessage = {
+  data: {
+    id: number;                 // The message id (sortable)
+    media_url: string;          // The media url for this message (searchable, sortable)
+    style: string;              // TODO: not present in API specification!
+    publish_at: string | null;  // TODO: not present in API specification!
+    ends_at: string | null;     // TODO: not present in API specification!
+    variants: ApiMessageVariant[];
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiMessageData = Flatten<Exclude<ApiMessage, ApiError>['data']>;
+
+const parseVideo = (url: string, id = getYoutubeVideoId(url)): string =>
+  (id ? `https://www.youtube.com/embed/${id}` : url);
+
+export const messageRevivers: Revivers<ApiMessage, Message> = {
+  id: undefined,
+  media_url: undefined,
+  style: undefined,
+  publish_at: undefined,
+  ends_at: undefined,
+  variants: undefined,
+
+  index: (data: ApiMessageData) => data.id,
+  image: (data: ApiMessageData) => parseVideo(data.media_url),
+  date: (data: ApiMessageData) => data.created_at as string,
+  read: () => false,
+  type: (data: ApiMessageData) => (data.style === 'regular' ? 'New feature' : 'Announcement'),
+  video: (data: ApiMessageData) => data.media_url.includes('www.youtube.com'),
+  title: (data: ApiMessageData) => data.variants[0].title,
+  text: (data: ApiMessageData) => data.variants[0].content,
+};
+
+export async function markMessageAsRead(messageId: number): Promise<Record<string, never>> {
+  const path = `/v1/messages/${messageId}/read`;
+
+  return request<ApiCommon, Record<string, never>>(path, null, null, { method: 'PUT' });
+}
+
+export function getYoutubeVideoId(url: string): string | undefined {
+  url = url.trim();
+
+  // Reference prefixed with a $ or video id
+  if (/^\$?[\w\-_]+$/.test(url)) {
+    return url;
+  }
+
+  const regex =
+    /(?:https?:\/\/)?(?:www\.)?youtu\.?be(?:\.com)?\/?.*(?:watch|embed)?(?:.*v=|v\/|\/)([\w\-_]+)&?/;
+
+  return (regex.exec(url) || [])[1];
+}