SDK — アプリの書き方

アプリは TypeScript で defineApp() を default export する 1 モジュールです。SDK（@lmile/app-kit）が型付きイベント・LMile API クライアント・構造化ログを提供します。開発リポジトリへのアクセスは [e-mail] に依頼してください。

最小のアプリ

import { defineApp } from "@lmile/app-kit";

export default defineApp({
  manifest: {
    name: "auto-reallocate",
    subscribes: ["routing_allocation_decided"],
    scopes: ["routing:write"],
  },
  handlers: {
    routing_allocation_decided: async (ctx) => {
      if (ctx.event.allocationStatus !== "unallocated") return;
      await ctx.api.routing.reallocate({ routingOrderId: ctx.event.routingOrderId });
      ctx.log.info("reallocate requested");
    },
  },
});

manifest

フィールド	型	必須	説明
name	string	✓	アプリ名
subscribes	string[]	✓	購読するイベント（Events）。LMile 側の購読設定はここから同期されます
scopes	string[]		必要な API 権限の宣言（例: routing:write）。現在は宣言のみで強制されません（将来 scope 単位で強制されます）
env	string[]		必要な環境変数のキー名宣言。値の登録は LMile 運用に依頼します（ctx.env で受け取り）
pii	boolean		明細 properties の受領要求。現在は無効（宣言しても properties は配信されません）

handlers

subscribes に宣言したイベントごとの async 関数です。

• handler が例外を throw する（または timeout する）と配信失敗として記録され、後で同じイベントが再配信されます — 冪等に書いてください
• handler を定義していないイベントが届いた場合は skip されます（失敗にはなりません）
• 実行時間に上限があります（既定 60 秒）。長い処理は外部システム側へ非同期に逃がしてください

ctx

フィールド	型	説明
ctx.shop	string	配信元の店舗ドメイン
ctx.eventType	string	イベント種別
ctx.event	object	型付きイベント payload（Events）。eventType ごとに型が確定します
ctx.idempotencyKey	string	イベント固有の冪等キー。同一イベントの再配信では同じ値
ctx.deliveryId	string	配信 ID（問い合わせ・追跡用）
ctx.api	object	LMile 公開 API の typed client（下記）
ctx.env	object	manifest.env で宣言した環境変数（値は実行環境が注入）
ctx.log	object	構造化ログ（下記）

ctx.api — LMile API の呼び返し

認証キーは実行環境が注入します（アプリのコードや設定にキーを書きません）。shop はリクエストボディに自動で同梱されます。

メソッド	エンドポイント
ctx.api.routing.reallocate(body)	POST /api/routing/reallocate
ctx.api.routing.changeSource(body)	POST /api/routing/change-source
ctx.api.routing.retryLabel(body)	POST /api/routing/shipment/retry-label
ctx.api.routing.secure(body)	POST /api/routing/secure
ctx.api.post(path, body)	任意の公開 POST エンドポイント（typed wrapper が無いもの）

HTTP エラーは LmileApiError（status / body）として throw されます。そのまま throw し直せば配信失敗 → 再送で回収されます。

ctx.log

info / warn / error の 3 レベル。エントリは実行ログに記録されます（1 実行あたり最大 50 件）。ログに顧客 PII（氏名・住所・名入れテキスト等）を書かないでください。

冪等性

配信は at-least-once / 順序保証なしのため、同じイベントが複数回届くことがあります。

• ctx.idempotencyKey は同一イベントの再配信で同じ値です。ctx.api の action 呼び出しの冪等キーに流用できます
• 「イベントの絶対状態を見て、必要なら action する」形にすると自然に冪等になります（差分や回数に依存しない）

詳細は Idempotency を参照。