@loongship-kit/data

Pure frontend TypeScript SDK for Loongship data APIs.

Install

pnpm add @loongship-kit/data

Client call

import lsData from "@loongship-kit/data";

const client = lsData.create({
  key: "your-user-key"
});

const res = await client.ship.search({
  kw: "cosco",
  max: 10
});

Per-request key overrides the client default:

params.key > client key

For baseURL, timeout, and headers, precedence is:

request options > client defaults

Hooks are client-scoped too:

const client = lsData.create({
  key: "your-user-key",
  hooks: {
    async onRequest(context) {
      return {
        ...context,
        requestOptions: {
          ...context.requestOptions,
          headers: {
            ...context.requestOptions.headers,
            "X-Trace-Id": crypto.randomUUID()
          }
        }
      };
    }
  }
});

API Modules Reference

The SDK is organized into several modules. Each module provides specific data queries through the client instance.

| Client Path | Description | Available Methods | |---|---|---| | client.ship | 船舶查询 (Ship) | search, detail, batchGet, area, nearby, archive | | client.typhoon | 台风查询 (Typhoon) | list, history, current, currentByName | | client.track | 轨迹查询 (Track) | query, full | | client.weather | 气象数据 (Weather) | current, forecast, rawDownload | | client.port | 港口数据 (Port) | callByShip, callByPort, callByShipPort, currentStatus | | client.push | 订阅推送 (Push) | updateShips, setCallbackUrl | | client.area | 区域数据 (Area) | create, list, delete, update | | client.tide | 潮汐数据 (Tide) | portSearch, record |

Note: All related parameter types and response data types are exported directly (e.g., TyphoonListParams, TyphoonListData).

Response

Successful requests return a normalized response:

{
  code: 0,
  data: []
}

To include the original raw payload:

const client = lsData.create({ key: "your-user-key" });

const res = await client.ship.search(
  { kw: "cosco" },
  { raw: true }
);

console.log(res.raw);

Mock mode

For demos or frontend integration, you can enable mock mode per request:

const client = lsData.create({ key: "your-user-key" });

const res = await client.ship.search(
  { kw: "cosco" },
  { mock: true }
);

It also works with SDK instances:

const weather = await client.weather.current(
  { lon: 121000000, lat: 31000000 },
  { mock: true, raw: true }
);

console.log(weather.raw);

Mock mode returns randomized type-shaped demo data and skips the real HTTP request. It is intended for UI demos only, so the returned content is not stable or business-accurate. signal still works in mock mode, while timeout is ignored because no network request is sent.

Interception and errors

If no hook handles them:

• business errors throw LoongshipApiError
• network / timeout / HTTP errors also throw LoongshipApiError

import lsData, { LoongshipApiError } from "@loongship-kit/data";

const client = lsData.create({ key: "your-user-key" });

try {
  await client.ship.search({ kw: "cosco", key: "bad-key" });
} catch (error) {
  if (error instanceof LoongshipApiError) {
    console.log(error.code, error.message);
  }
}

The SDK may also throw:

• MissingApiKeyError when no usable key is available
• CanceledError when a request is aborted via AbortController

To intercept request lifecycle for one client, use:

• hooks.onRequest
• hooks.onResponse
• hooks.onError

Cancel request

const controller = new AbortController();

const promise = client.ship.search(
  { kw: "cosco" },
  { signal: controller.signal }
);

controller.abort();

Documentation

Generate and preview the VitePress documentation locally:

pnpm run docs:dev

To build the static HTML site:

pnpm run docs:build