@globalfishingwatch/skills 0.0.1

package/src/encode-url/references/query-params.md

@@ -0,0 +1,114 @@
+# GFW map query params (state)
+
+Pass these unabbreviated in `state` — the encoder abbreviates them.
+Source of truth (params documented with JSDoc — read these when a param is missing here):
+`apps/fishing-map/types/index.ts` (`WorkspaceState`/`AppState`/`QueryParams`), `apps/fishing-map/features/reports/reports.types.ts` (`ReportState`), `apps/fishing-map/features/vessel/vessel.types.ts` (`VesselProfileState`), `apps/fishing-map/features/search/search.types.ts` (`VesselSearchState`).
+Defaults live in `DEFAULT_WORKSPACE` (`apps/fishing-map/data/config.ts`) and `DEFAULT_REPORT_STATE` (`features/reports/reports.config.ts`).
+
+## Core (all routes)
+
+| Param                           | Type                            | Notes                                                                                                                           |
+| ------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `latitude`, `longitude`, `zoom` | number                          | Viewport. zoom 0 = world, ~4-6 = country, ~12 = port                                                                            |
+| `start`, `end`                  | ISO datetime                    | Time range, e.g. `2026-07-01T00:00:00.000Z`                                                                                     |
+| `dataviewInstances`             | array                           | The layers (see layers.md)                                                                                                      |
+| `timebarVisualisation`          | string                          | `heatmap` (activity) \| `heatmapDetections` \| `events` \| `vessel` \| `vesselGroup` \| `environment`                           |
+| `visibleEvents`                 | array \| `all` \| `none`        | Event types on vessel tracks: `fishing`, `encounter`, `port_visit`, `loitering`, `gaps` (default `all`)                         |
+| `timebarGraph`                  | string                          | `speed` \| `elevation` \| `none`                                                                                                |
+| `sidebarOpen`                   | boolean                         |                                                                                                                                 |
+| `readOnly`                      | boolean                         | Share links that shouldn't be edited                                                                                            |
+| `daysFromLatest`                | number                          | Rolling window ending at latest available day                                                                                   |
+| `bivariateDataviews`            | [id, id]                        | Two activity layers compared in one bivariate ramp                                                                              |
+| `mapAnnotations`, `mapRulers`   | arrays                          | User drawings/measurements; toggle without removing via `mapAnnotationsVisible` / `mapRulersVisible` (booleans, default `true`) |
+| `mapDrawing`                    | `polygons` \| `points` \| false | Enables the draw-on-map feature; `mapDrawingEditId` targets an existing drawn feature for edit                                  |
+| `activityVisualizationMode`     | string                          | Render mode for activity layers: `heatmap` (default) \| `heatmap-high-res` \| `heatmap-low-res` \| `positions`                  |
+| `detectionsVisualizationMode`   | string                          | Same values as activity; for detections layers (default `heatmap`)                                                              |
+| `environmentVisualizationMode`  | string                          | `heatmap` \| `heatmap-low-res` (default) — no high res for environment layers                                                   |
+| `vesselGroupsVisualizationMode` | string                          | `footprint` (default) \| `footprint-high-res`                                                                                   |
+| `vesselsColorBy`                | string                          | Property coloring vessel tracks/points: `track` \| `speed` \| `elevation`                                                       |
+
+Internal/auto-generated params — never set them: `reportAreaBounds`, `skipColorDomainSampling`, `migramarLayer`, `includeRelatedIdentities`, `trackCorrectionId`, `sidePanelId`/`sidePanelSubcontentId`/`sidePanelContent`.
+
+## dataviewInstances item
+
+```json
+{
+  "id": "ais", // instance id (layers.md)
+  "dataviewId": "apparent-fishing-effort-ais-v-{PIPE_DATASET_VERSION}", // only for layers added on top of defaults; version token resolved by the encoder
+  "config": {
+    "visible": true,
+    "color": "#9CA4FF", // set together with colorRamp — use that ramp's hex (see palette below)
+    "colorRamp": "lilac", // teal|orange|magenta|yellow|lilac|sky|green|red|salmon
+    "filters": { "flag": ["FRA"], "geartype": ["trawlers"] }
+  }
+}
+```
+
+`color`/`colorRamp` are one choice, not two. Pick a ramp and set `color` to its paired hex:
+
+| colorRamp | color     | colorRamp | color     | colorRamp | color     |
+| --------- | --------- | --------- | --------- | --------- | --------- |
+| teal      | `#00FFBC` | sky       | `#00EEFF` | green     | `#A6FF59` |
+| lilac     | `#9CA4FF` | red       | `#FF6854` | orange    | `#FFAA0D` |
+| salmon    | `#FFAE9B` | yellow    | `#FFEA00` | magenta   | `#FF64CE` |
+
+To show the SAME dataset twice with different filters (e.g. Spanish vs French fishing), reuse the default instance (`ais`) for one and add a second instance with a unique id (`fishing-effort-ais__<timestamp>`) + `dataviewId`.
+
+## Area report (`report` route)
+
+| Param                                                                                 | Values                                                                                                             |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `reportCategory`                                                                      | `activity` (default) \| `detections` \| `events` \| `environment` \| `others` \| `vessel-groups`                   |
+| `reportActivitySubCategory`                                                           | `fishing` \| `presence` — sub-filter within an activity report                                                     |
+| `reportDetectionsSubCategory`                                                         | `sar` \| `viirs` \| `sentinel-2` — sub-filter within a detections report                                           |
+| `reportEventsSubCategory`                                                             | event type within an events report: `encounter` (default) \| `loitering` \| `port_visit` \| `gap`                  |
+| `reportVesselsSubCategory`                                                            | vessels-tab sub-tab: `flag` (default) \| `geartype` \| `vesselType` \| `source` \| `coverage`                      |
+| `reportActivityGraph`                                                                 | `evolution` (default) \| `beforeAfter` \| `periodComparison` \| `datasetComparison`                                |
+| `reportTimeComparison`                                                                | `{ "start", "compareStart", "duration", "durationType": "days"\|"months" }` — for `beforeAfter`/`periodComparison` |
+| `reportComparisonDataviewIds`                                                         | `{ "main", "compare" }` dataview ids — for `datasetComparison`                                                     |
+| `reportVesselGraph`                                                                   | `flag` (default) \| `geartype` \| `vesselType`                                                                     |
+| `reportBufferValue` / `reportBufferUnit` / `reportBufferOperation`                    | number / `nauticalmiles`\|`kilometers` / `dissolve`\|`difference`                                                  |
+| `reportVesselFilter`                                                                  | free-text filter on the vessels list — see syntax below                                                            |
+| `reportVesselPage`, `reportResultsPerPage`                                            | pagination (page is 0-based; per-page min 10, max 50, default 10)                                                  |
+| `reportVesselOrderProperty` / `reportVesselOrderDirection`                            | sort: `shipname` (default) \| `flag` \| `shiptype` / `asc` (default) \| `desc`                                     |
+| `reportLoadVessels`                                                                   | boolean, load vessel list immediately                                                                              |
+| `reportEventsGraph`                                                                   | events-report chart: `evolution` (default) \| `byFlag` \| `byRFMO` \| `byFAO` \| `byEEZ`                           |
+| `reportEventsPortsFilter`, `reportEventsPortsPage`, `reportEventsPortsResultsPerPage` | ports list controls in an events report (same semantics as the vessel-table ones)                                  |
+
+Note: the URL param is `reportResultsPerPage` even though the app state field is named `reportVesselResultsPerPage` — always use `reportResultsPerPage` in `state`.
+
+`reportVesselFilter` syntax (also `reportEventsPortsFilter`): comma = search by multiple fields, `|` = OR, leading `-` = exclude. E.g. `flag:china, gear:trawlers`, `-spain`, `cargo|passenger`.
+
+## Ports report (`ports-report` route)
+
+`portsReportName` (e.g. `CAMARONES`), `portsReportCountry` (ISO3), `portsReportDatasetId` (`public-global-port-visits-events:v4.0`).
+
+## Vessel profile (`vessel` route)
+
+| Param                                       | Values                                                          |
+| ------------------------------------------- | --------------------------------------------------------------- |
+| `vesselDatasetId`                           | `public-global-vessel-identity:v4.0`                            |
+| `vesselSelfReportedId` / `vesselRegistryId` | vessel identity ids                                             |
+| `vesselIdentitySource`                      | `selfReportedInfo` \| `registryInfo`                            |
+| `vesselSection`                             | `activity` \| `related_vessels` \| `areas` \| `insights`        |
+| `vesselArea`                                | `fao` \| `eez` \| `mpa` \| `rfmo`                               |
+| `vesselRelated`                             | `encounters` \| `owners` — when `vesselSection=related_vessels` |
+| `vesselActivityMode`                        | `voyage` \| `type`                                              |
+
+## Vessel search (`vessel-search` route)
+
+| Param           | Notes                                                                                                                                  |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `query`         | free text: name, MMSI, IMO, callsign                                                                                                   |
+| `searchOption`  | `basic` (default) \| `advanced`                                                                                                        |
+| `sources`       | dataset ids restricting the search (advanced only)                                                                                     |
+| advanced fields | `flag` (array ISO3), `owner`, `ssvid` (MMSI), `imo`, `callsign`, `geartypes`, `shiptypes`, `transmissionDateFrom`/`transmissionDateTo` |
+| `infoSource`    | identity source filter                                                                                                                 |
+
+`transmissionDateFrom`/`transmissionDateTo` are advanced search FIELDS (dates, `YYYY-MM-DD`) — different namespace from the `firstTransmissionDate`/`lastTransmissionDate` URL params (`fTD`/`lTD`) that always appear (often empty) in search URLs.
+
+## User page (`user` route)
+
+`userTab`: `info` | `workspaces` | `datasets` | `reports` | `vesselGroups`.
+
+<!-- Maintainers: every enumerated value above maps to a source symbol — see "Value sources" in ../MAINTENANCE.md for update checks. -->

package/src/encode-url/references/routes.md

@@ -0,0 +1,24 @@
+# GFW map routes
+
+App served under basename `/map` (already included in the script's `path` output).
+Source: `apps/fishing-map/routes/_app` (TanStack Router file routes).
+
+| Route type            | Path pattern                                                 | Path params           | When to use                                                                          |
+| --------------------- | ------------------------------------------------------------ | --------------------- | ------------------------------------------------------------------------------------ |
+| `workspace`           | `/` or `/$category/$workspaceId`                             | category, workspaceId | Browse/compare layers on the map                                                     |
+| `workspaces-list`     | `/$category`                                                 | category              | List curated workspaces of a category                                                |
+| `report`              | `/$category/$workspaceId/report/$datasetId/$areaId`          | + datasetId, areaId   | Aggregated report over an area (EEZ/FAO/RFMO/MPA)                                    |
+| `report` (global)     | `/$category/$workspaceId/report`                             | — (no datasetId/areaId) | Whole-world aggregated report; omit `datasetId`+`areaId`, category defaults to `reports` |
+| `report` (saved)      | `/report/$reportId`                                          | reportId              | Open a user-saved report                                                             |
+| `vessel`              | `/$category/$workspaceId/vessel/$vesselId`                   | + vesselId            | Vessel profile (identity, track, events)                                             |
+| `vessel-search`       | `/$category/$workspaceId/vessel-search`                      | —                     | Search vessels by name/MMSI/IMO or advanced filters                                  |
+| `vessel-group-report` | `/$category/$workspaceId/vessel-group-report/$vesselGroupId` | + vesselGroupId       | Report over a vessel group                                                           |
+| `ports-report`        | `/$category/$workspaceId/ports-report/$portId`               | + portId              | Port activity profile (visits, vessels)                                              |
+| `user`                | `/user`                                                      | —                     | User info, saved workspaces (`userTab=workspaces`), datasets, reports, vessel groups |
+
+- `category`: `fishing-activity` (default) | `marine-manager` | `reports`
+- `workspaceId`: `default-public` (default public workspace)
+- report `datasetId` values: `public-eez-areas`, `public-fao-major`, `public-rfmo`, `public-mpa-all`
+- `areaId`: numeric for EEZs (see `areas.json`), FAO major area code, RFMO id
+- `vesselId`: GFW vessel id (uuid-like, from vessel search results)
+- `portId`: e.g. `arg-camarones` (see `ports.json`)

package/src/encode-url/routes.ts

@@ -0,0 +1,166 @@
+import {
+  DEFAULT_PATH_BASENAME,
+  DEFAULT_WORKSPACE_CATEGORY,
+  DEFAULT_WORKSPACE_ID,
+  ROUTE_PATHS,
+} from '@fishing-map/config'
+
+export { DEFAULT_PATH_BASENAME as DEFAULT_BASENAME }
+
+export type MapRouteType =
+  | 'workspace'
+  | 'workspaces-list'
+  | 'report'
+  | 'vessel'
+  | 'vessel-search'
+  | 'vessel-group-report'
+  | 'ports-report'
+  | 'user'
+
+export type MapRouteParams = {
+  category?: string
+  workspaceId?: string
+  datasetId?: string
+  areaId?: string
+  reportId?: string
+  vesselId?: string
+  vesselGroupId?: string
+  portId?: string
+}
+
+export type MapRoute = { type: MapRouteType } & MapRouteParams
+
+export type RouteNavigation = {
+  to: string
+  params: Record<string, string>
+}
+
+const required = (route: MapRoute, param: keyof MapRouteParams): string => {
+  const value = route[param]
+  if (!value) {
+    throw new Error(`route.${param} is required for route type "${route.type}"`)
+  }
+  return value
+}
+
+/**
+ * Returns the TanStack Router `to` pattern and `params` for a route,
+ * matching the file routes in apps/fishing-map/routes/_app
+ */
+export const getRouteNavigation = (route: MapRoute): RouteNavigation => {
+  const category = route.category || DEFAULT_WORKSPACE_CATEGORY
+  const workspaceId = route.workspaceId || DEFAULT_WORKSPACE_ID
+  const workspaceParams = { category, workspaceId }
+  switch (route.type) {
+    case 'workspace':
+      if (!route.category && !route.workspaceId) {
+        return { to: ROUTE_PATHS.HOME, params: {} }
+      }
+      return { to: ROUTE_PATHS.WORKSPACE, params: workspaceParams }
+    case 'workspaces-list':
+      return { to: ROUTE_PATHS.WORKSPACES_LIST, params: { category } }
+    case 'report':
+      if (route.reportId) {
+        return { to: ROUTE_PATHS.REPORT, params: { reportId: route.reportId } }
+      }
+      if (!route.datasetId && !route.areaId) {
+        return {
+          to: ROUTE_PATHS.WORKSPACE_REPORT,
+          params: { category: route.category || 'reports', workspaceId },
+        }
+      }
+      return {
+        to: ROUTE_PATHS.WORKSPACE_REPORT_FULL,
+        params: {
+          ...workspaceParams,
+          datasetId: required(route, 'datasetId'),
+          areaId: required(route, 'areaId'),
+        },
+      }
+    case 'vessel':
+      if (!route.category && !route.workspaceId) {
+        return { to: ROUTE_PATHS.VESSEL, params: { vesselId: required(route, 'vesselId') } }
+      }
+      return {
+        to: ROUTE_PATHS.WORKSPACE_VESSEL,
+        params: { ...workspaceParams, vesselId: required(route, 'vesselId') },
+      }
+    case 'vessel-search':
+      return { to: ROUTE_PATHS.WORKSPACE_SEARCH, params: workspaceParams }
+    case 'vessel-group-report':
+      return {
+        to: ROUTE_PATHS.VESSEL_GROUP_REPORT,
+        params: { ...workspaceParams, vesselGroupId: required(route, 'vesselGroupId') },
+      }
+    case 'ports-report':
+      return {
+        to: ROUTE_PATHS.PORT_REPORT,
+        params: { ...workspaceParams, portId: required(route, 'portId') },
+      }
+    case 'user':
+      return { to: ROUTE_PATHS.USER, params: {} }
+    default:
+      throw new Error(`Unknown route type "${(route as MapRoute).type}"`)
+  }
+}
+
+export const buildRoutePath = (navigation: RouteNavigation): string => {
+  const path = navigation.to
+    .split('/')
+    .map((segment) =>
+      segment.startsWith('$')
+        ? encodeURIComponent(navigation.params[segment.slice(1)] || '')
+        : segment
+    )
+    .join('/')
+  return path === '' ? '/' : path
+}
+
+// Static-segment patterns listed before parametric ones of the same length,
+// so e.g. /user wins over /$category. Types map each ROUTE_PATHS pattern.
+const ROUTE_PATTERNS: [string, MapRouteType][] = [
+  [ROUTE_PATHS.USER, 'user'],
+  [ROUTE_PATHS.SEARCH, 'vessel-search'],
+  [ROUTE_PATHS.REPORT, 'report'],
+  [ROUTE_PATHS.VESSEL, 'vessel'],
+  [ROUTE_PATHS.WORKSPACES_LIST, 'workspaces-list'],
+  [ROUTE_PATHS.WORKSPACE, 'workspace'],
+  [ROUTE_PATHS.WORKSPACE_SEARCH, 'vessel-search'],
+  [ROUTE_PATHS.WORKSPACE_VESSEL, 'vessel'],
+  [ROUTE_PATHS.WORKSPACE_REPORT, 'report'],
+  [ROUTE_PATHS.WORKSPACE_REPORT_FULL, 'report'],
+  [ROUTE_PATHS.VESSEL_GROUP_REPORT, 'vessel-group-report'],
+  [ROUTE_PATHS.PORT_REPORT, 'ports-report'],
+]
+
+const matchPattern = (pattern: string, segments: string[]): MapRouteParams | undefined => {
+  const patternSegments = pattern.split('/').filter(Boolean)
+  if (patternSegments.length !== segments.length) return undefined
+  const params: Record<string, string> = {}
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternSegment = patternSegments[i]
+    if (patternSegment.startsWith('$')) {
+      params[patternSegment.slice(1)] = segments[i]
+    } else if (patternSegment !== segments[i]) {
+      return undefined
+    }
+  }
+  return params
+}
+
+/**
+ * Matches a pathname (basename already stripped) against the ROUTE_PATHS patterns
+ */
+export const matchRoutePath = (pathname: string): MapRoute => {
+  const segments = pathname.split('/').filter(Boolean).map(decodeURIComponent)
+  if (segments.length === 0) {
+    return { type: 'workspace' }
+  }
+  for (const [pattern, type] of ROUTE_PATTERNS) {
+    const params = matchPattern(pattern, segments)
+    if (params) {
+      return { type, ...params }
+    }
+  }
+  return { type: 'workspace', category: segments[0], workspaceId: segments[1] }
+}

package/src/encode-url/scripts/encode-url.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import './register-gfw-resolver.mjs'
+
+const readStdin = async () => {
+  let data = ''
+  for await (const chunk of process.stdin) data += chunk
+  return data
+}
+
+const input = process.argv[2] && process.argv[2] !== '-' ? process.argv[2] : await readStdin()
+if (!input?.trim()) {
+  console.error(
+    `Usage: node encode-url.mjs '{"route":{"type":"workspace"},"state":{...}}' (or pipe JSON via stdin)`
+  )
+  process.exit(1)
+}
+
+const { encodeMapUrl } = await import('@globalfishingwatch/skills/encode-url')
+
+try {
+  const result = encodeMapUrl(JSON.parse(input))
+  console.log(JSON.stringify(result, null, 2))
+} catch (error) {
+  console.error(error.message)
+  process.exit(1)
+}

package/src/encode-url/scripts/register-gfw-resolver.mjs

@@ -0,0 +1,24 @@
+import { existsSync } from 'node:fs'
+import { registerHooks } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+// Each skill ships its own self-contained bundle next to it. Resolve it from either layout:
+// - dist/<skill>/scripts (dist output, this skill copied standalone) -> ../index.js
+// - <skill>/scripts (monorepo source, unbuilt) -> ../../dist/<skill>/index.js
+const skillDir = fileURLToPath(new URL('..', import.meta.url))
+const skillName = path.basename(skillDir)
+const SPECIFIER = `@globalfishingwatch/skills/${skillName}`
+const BUNDLE = [
+  path.join(skillDir, 'index.js'),
+  path.join(skillDir, '..', '..', 'dist', skillName, 'index.js'),
+].find(existsSync)
+
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    if (specifier === SPECIFIER && BUNDLE) {
+      return { url: pathToFileURL(BUNDLE).href, format: 'module', shortCircuit: true }
+    }
+    return nextResolve(specifier, context)
+  },
+})

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './decode-url/decode'
+export * from './decode-url/workspaces'
+export * from './encode-url/config'
+export * from './encode-url/dictionary'
+export * from './encode-url/encode'
+export * from './encode-url/routes'