@mapcreator/api 3.3.7 → 5.0.0-alpha.100

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,70 @@
+import {
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  type Revivers,
+  defaultListHeader,
+  getSearchParams,
+  request,
+} 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,
+};
+
+export async function listMapstyleSets(jobTypeId?: number): Promise<MapstyleSet[]> {
+  const pathname = `/v1/mapstyles/sets`;
+  const query = jobTypeId !== undefined ? getSearchParams({ search: { job_type_id: jobTypeId } }) : null;
+  const path = query ? `${pathname}?${query}` : pathname;
+  const options = { revivers: mapstyleSetRevivers };
+
+  type ApiMapstyleSetArray = {
+    data: ApiMapstyleSetData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiMapstyleSetArray, MapstyleSet>(path, null, defaultListHeader, options);
+}

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];
+}

package/src/api/organisation.ts

@@ -0,0 +1,97 @@
+import type { ApiJobShareArray, JobShare } from './jobShare.js';
+import { type JobSearchResult, listJobs } from './apiCommon.js';
+import {
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  type Revivers,
+  defaultListHeader,
+  getSearchParams,
+  myOrganisations,
+  request,
+} from '../utils.js';
+
+export type Organisation = {
+  id: number;
+  name: string;
+  credits: number;
+  settings: string | null;
+  vectorToken: string;
+  trialExpiresAt: string | undefined;
+  exportTemplates: string;
+  contractType: string;
+  subscriptionType: string;
+};
+
+export type ApiOrganisation = {
+  data: {
+    id: number;                 // The id of the organisation (sortable)
+    name: string;               // The name of the organisation (searchable, sortable)
+    manager_id: number;         // The id of the manager of the organisation (searchable)
+    sales_representative_id: number | null; // The id of the sales representative (searchable)
+    credits: number;            // The credits of the organisation (searchable, sortable)
+    country: string | null;     // The country where the organisation is from (searchable, sortable)
+    address: string | null;     // The address of the organisation (searchable, sortable)
+    city: string | null;        // The city of the organisation (searchable, sortable)
+    settings: string | null;    // An object with settings for the organisations
+    vector_token: string;       // The vector API token of the organisation
+    tiles_on_domain: boolean;   // TODO: not present in API specification!
+    trial_expires_at: string | null; // The datetime when the user's trial expires
+    parent_id: number | null;   // TODO: not present in API specification!
+    hatching_pattern_svg_set_id: number | null; // A svg set that overrides the default h-pattern
+    template_settings: string | null; // TODO: not present in API specification!
+    contractType: string | null; // The name of signed contract
+    subscriptionType: string | null; // The name of subscription type
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiOrganisationData = Flatten<Exclude<ApiOrganisation, ApiError>['data']>;
+
+export const organisationRevivers: Revivers<ApiOrganisation, Organisation> = {
+  manager_id: undefined,
+  sales_representative_id: undefined,
+  country: undefined,
+  address: undefined,
+  city: undefined,
+  tiles_on_domain: undefined,
+  parent_id: undefined,
+  hatching_pattern_svg_set_id: undefined,
+  template_settings: undefined,
+
+  trialExpiresAt: (data: ApiOrganisationData) => data.trial_expires_at ?? undefined,
+  exportTemplates: (data: ApiOrganisationData) => data.template_settings ?? '{}',
+};
+
+export async function getOrganisation(
+  organisationId: number | typeof myOrganisations = myOrganisations,
+): Promise<Organisation> {
+  const path = `/v1/organisations/${organisationId}`;
+  const options = { revivers: organisationRevivers };
+
+  return request<ApiOrganisation, Organisation>(path, null, null, options);
+}
+
+export async function listOrganisationJobs(
+  organisationId: number | typeof myOrganisations,
+  title: string,
+  shared: boolean,
+  page: number,
+  options?: Record<string, unknown>,
+): Promise<JobSearchResult> {
+  const search = { ...options, ...{ hidePrivate: true, shared } };
+
+  return listJobs(`/v1/organisations/${organisationId}/jobs`, title, page, search);
+}
+
+export async function listOrganisationShares(jobId: number): Promise<JobShare[]> {
+  const pathname = `/v1/organisations/${myOrganisations}/shares`;
+  const query = getSearchParams({
+    search: {
+      job_id: `=:${jobId}`,
+    },
+  });
+  const path = `${pathname}?${query}`;
+
+  return request<ApiJobShareArray, JobShare>(path, null, defaultListHeader);
+}

package/src/api/resources.ts

@@ -0,0 +1,153 @@
+import { type ApiOrganisationData, type Organisation, organisationRevivers } from './organisation.js';
+import { type ApiDimensionSetData, type DimensionSet, dimensionSetRevivers } from './dimensionSet.js';
+import { type ApiMapstyleSetData, type MapstyleSet, mapstyleSetRevivers } from './mapstyleSet.js';
+import { type ApiFontFamilyData, type FontFamily, fontFamilyRevivers } from './fontFamily.js';
+import { type ApiDimensionData, type Dimension, dimensionRevivers } from './dimension.js';
+import { type ApiFeatureData, type Feature, featureRevivers } from './feature.js';
+import { type ApiJobTypeData, type JobType, jobTypeRevivers } from './jobType.js';
+import { type ApiMessageData, type Message, messageRevivers } from './message.js';
+import { type ApiSvg, type ApiSvgData, type Svg, svgRevivers } from './svg.js';
+import { type ApiSvgSetData, type SvgSet, svgSetRevivers } from './svgSet.js';
+import { type ApiLayerData, type Layer, layerRevivers } from './layer.js';
+import { type ApiColorData, type Color, colorRevivers } from './color.js';
+import { type ApiUserData, type User, userRevivers } from './user.js';
+import { type ApiFontData, type Font, fontRevivers } from './font.js';
+import type { CamelCasedProperties } from 'type-fest';
+import {
+  type ApiCommon,
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Revivers,
+  getContext,
+  myUser,
+  processData,
+  request,
+} from '../utils.js';
+
+export type CustomFeature =
+  | 'custom_dpi'
+  | 'disable_company_maps'
+  | 'eps_plus_log'
+  | 'filename_is_job_title'
+  | 'iframe_sandbox_attributes'
+  | 'keep_layer_visibility'
+  | 'no_copyright'
+  | 'only_shared_company_maps'
+  | 'pdf_output'
+  | 'show_frelex_links'
+  | 'svg_output'
+  | 'svg-georef'
+  | 'tiff_output'
+  | 'video_export'
+  | 'v5_video'
+  | 'web_output'
+  | 'web_download'
+  | 'new_single_and_grouped_areas_menu'
+  | 'export_templates'
+  | 'export_video_tracking_data'
+  | 'hosted_svg_output'
+  | 'hosted_png_output'
+  | 'hosted_jpg_output'
+  | 'developer_menu';
+
+export interface Resources {
+  organisation: Organisation;
+  user: User;
+  features: CustomFeature[];
+  colors: Color[];
+  svgs: Svg[];
+  dimensions: Dimension[];
+  dimensionSets: DimensionSet[];
+  mapstyleSets: MapstyleSet[];
+  jobTypes: JobType[];
+  messages: Message[];
+  svgSets: SvgSet[];
+  layers: Layer[];
+  fonts: Font[];
+  fontFamilies: FontFamily[];
+}
+
+type ApiResources = {
+  data: {
+    user: ApiUserData;
+    organisation: ApiOrganisationData;
+    features: ApiFeatureData[];
+    colors: ApiColorData[];
+    svgs: ApiSvgData[];
+    messages: {
+      read: ApiMessageData[];
+      unread: ApiMessageData[];
+    };
+    dimensions: ApiDimensionData[];
+    dimension_sets: ApiDimensionSetData[];
+    mapstyle_sets: ApiMapstyleSetData[];
+    hatching_svgs?: ApiSvgData[];
+    job_types: ApiJobTypeData[];
+    svg_sets: ApiSvgSetData[];
+    layers: ApiLayerData[];
+    fonts: ApiFontData[];
+    font_families: ApiFontFamilyData[];
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiResourcesData = Exclude<ApiResources, ApiError>['data'];
+
+export type FillPattern = {
+  name: string;
+  string: string;
+};
+
+export async function loadResources(): Promise<Resources> {
+  const path = `/v1/users/${myUser}/resources`;
+  const raw = await request<ApiResources, CamelCasedProperties<ApiResourcesData>>(path);
+
+  const { user, organisation, messages: { read, unread } } = raw;
+  const readMessages = read.map(processData, getContext(messageRevivers)) as Message[];
+  const unreadMessages = unread.map(processData, getContext(messageRevivers)) as Message[];
+
+  readMessages.forEach(message => (message.read = true));
+
+  const allMessages = [...readMessages, ...unreadMessages];
+
+  allMessages.sort((m1, m2) => m2.date.localeCompare(m1.date));
+
+  const mcSvgRevivers: Revivers<ApiSvg, Svg> = {
+    ...svgRevivers,
+    name: (data: ApiSvgData) => `mc-image-${data.name}`,
+  };
+
+  return {
+    // @ts-expect-error TS2345
+    user: processData.call(getContext(userRevivers), user) as User,
+    // @ts-expect-error TS2345
+    organisation: processData.call(getContext(organisationRevivers), organisation) as Organisation,
+
+    features: (raw.features.map(processData, getContext(featureRevivers)) as Feature[]).map(
+      feature => feature.name,
+    ) as CustomFeature[],
+    colors: raw.colors.map(processData, getContext(colorRevivers)) as Color[],
+    svgs: raw.svgs.map(processData, getContext(mcSvgRevivers)) as Svg[],
+    dimensions: raw.dimensions.map(processData, getContext(dimensionRevivers)) as Dimension[],
+    dimensionSets: raw.dimensionSets.map(processData, getContext(dimensionSetRevivers)) as DimensionSet[],
+    mapstyleSets: raw.mapstyleSets.map(processData, getContext(mapstyleSetRevivers)) as MapstyleSet[],
+    jobTypes: raw.jobTypes.map(processData, getContext(jobTypeRevivers)) as JobType[],
+    messages: allMessages,
+    layers: (raw.layers?.map(processData, getContext(layerRevivers)) ?? []) as Layer[],
+    svgSets: (raw.svgSets?.map(processData, getContext(svgSetRevivers)) ?? []) as SvgSet[],
+    fonts: (raw.fonts?.map(processData, getContext(fontRevivers)) ?? []) as Font[],
+    fontFamilies: (raw.fontFamilies?.map(processData, getContext(fontFamilyRevivers)) ?? []) as FontFamily[],
+  };
+}
+
+export async function getCountries(): Promise<string[]> {
+  return request<ApiCommon, string, true>(`/v1/resources/countries`);
+}
+
+export async function getFunctions(): Promise<string[]> {
+  return request<ApiCommon, string, true>(`/v1/resources/functions`);
+}
+
+export async function getIndustries(): Promise<string[]> {
+  return request<ApiCommon, string, true>(`/v1/resources/industries`);
+}

package/src/api/svg.ts

@@ -0,0 +1,33 @@
+import { type ApiCommonData, type ApiError, type ApiSuccess, type Flatten, type Revivers, request } from '../utils.js';
+
+export type Svg = {
+  id: number;
+  svgSetId: number;
+  name: string;
+  string: string;
+};
+
+export type ApiSvg = {
+  data: {
+    id: number;                 // The id of the svg (sortable)
+    svg_set_id: number;         // The id of the svg_set related to this svg
+    name: string;               // The name of the svg (searchable, sortable)
+    string: string;             // The XML of the svg
+    resize_factor: number;      // The number of the resize for svg (searchable, sortable)
+    order: number;              // The order in which this svg appears in the set (sortable)
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiSvgData = Flatten<Exclude<ApiSvg, ApiError>['data']>;
+
+export const svgRevivers: Revivers<ApiSvg, Svg> = {
+  resize_factor: undefined,
+  order: undefined,
+};
+
+export async function getSvg(svgId: number): Promise<Svg> {
+  const path = `/v1/svgs/${svgId}`;
+  const options = { revivers: svgRevivers };
+
+  return request<ApiSvg, Svg>(path, null, null, options);
+}

package/src/api/svgSet.ts

@@ -0,0 +1,56 @@
+import { type ApiSvgData, type Svg, svgRevivers } from './svg.js';
+import {
+  type ApiCommonData,
+  type ApiError,
+  type ApiSuccess,
+  type Flatten,
+  type Revivers,
+  defaultListHeader,
+  getSearchParams,
+  request,
+} from '../utils.js';
+
+export type SvgSet = {
+  id: number;
+  name: string;
+  type: string;
+};
+
+export type ApiSvgSet = {
+  data: {
+    id: number;                 // The id of the set (searchable, sortable)
+    name: string;               // The name of the set (searchable, sortable)
+    type: string;               // The type of the svg set (searchable, sortable)
+    supports_interactive: boolean; // If the set is interactive (searchable, sortable)
+    supports_mapcreator: boolean; // If this set can be used on Mapcreator (searchable, sortable)
+    supports_v3: boolean;       // If this set can be used on v3 (searchable, sortable)
+    order?: number;             // TODO: not present in API specification!
+  } & ApiCommonData;
+} & Omit<ApiSuccess, 'data'> | ApiError;
+
+export type ApiSvgSetData = Flatten<Exclude<ApiSvgSet, ApiError>['data']>;
+
+export const svgSetRevivers: Revivers<ApiSvgSet, SvgSet> = {
+  supports_interactive: undefined,
+  supports_mapcreator: undefined,
+  supports_v3: undefined,
+  order: undefined,
+};
+
+export async function listSvgSetSvgs(svgSetId: number): Promise<Svg[]> {
+  const pathname = `/v1/svgs/sets/${svgSetId}/items`;
+  const query = getSearchParams({
+    search: {
+      supports_mapcreator: '1',
+    },
+    sort: 'order,id',
+  });
+  const path = `${pathname}?${query}`;
+  const options = { revivers: svgRevivers };
+
+  type ApiSvgArray = {
+    data: ApiSvgData[];
+  } & Omit<ApiSuccess, 'data'> | ApiError;
+
+  return request<ApiSvgArray, Svg>(path, null, defaultListHeader, options);
+}