@originaiagent/core-master-sdk

v0.6.0-alpha.1

Published

a month ago

Core Master SDK — all-tools shared origin-core master data access layer

Downloads

323

0High
0Medium
0Low

originai123

@originaiagent/core-master-sdk

全ツール共通の origin-core マスタ参照 SDK。設計書: docs/core-master-sdk-design.md

Status

v0.3.0-alpha.1 (dev_backlog dc20572e): Write Support 初回。4 テーブル PATCH 実装。
- products.patch(id, body, opts?) / productCosts.patch(id, body, opts?) — 既存 resource に追加
- productSpecs.patch(id, body, opts?) / productSkus.patch(id, body, opts?) — 新規 (write のみ、read は v0.4 以降)
- 追加エラー型: CoreMasterPreconditionFailedError (412 If-Match mismatch)
- 追加 header: X-Tool-Name (必須) / X-User-Email / If-Match / Idempotency-Key (SDK 自動 UUID 付与)
- PATCH retry: GET と同じ指数バックオフ (Idempotency-Key は固定で安全再送)
- 仕様根拠: guides slug=core-write-sdk-spec-v03-draft §2 D-3 確定版
v0.2.0-alpha.2 (dev_backlog afd1c531): product_field_settings SEED 補完に合わせ、型定義 2 種を追加移転。
- CoreProductFieldSetting — product_field_settings 行 (一括除外タブ候補リスト駆動)
- CoreProductFieldExclusion — product_field_exclusions 行 (製品単位の「該当なし」項目)
- resource client 追加は別 PR (dev_backlog 22107c50 配下) で実施予定
v0.2.0-alpha.1 (M4): ec-manager 適用のため bulk API 3 本を追加。
- productCosts.listByIds(productIds) / listLatestByIds(productIds) — 500 件自動分割、concurrency 3
- mallIdentifiers.listByMall(mallCode) — モール全件の識別子列挙
- mallProfitability.listByMall(mallCode) — モール全件の収益性列挙（本 SDK 版で型移転）
- vitest 導入（src/resources/**.test.ts, src/client/fetchJson.test.ts）、カバレッジ閾値 lines 85% / branches 80%
v0.1.0-alpha.1 (M2/M3): 型・エラー階層・createCoreMaster 本体 + read 4 リソース
移転済 interface (11 種): CoreValueSourceEntry, CoreValueSources, CoreProductGroup, CoreProduct, CoreProductCost, CoreMall, CoreMallIdentifier, CoreMallCodeDefinition, CoreMallProfitability, CoreProductFieldSetting, CoreProductFieldExclusion

Install (GitHub Packages, consumers)

1. `.npmrc`（consumer repo のルートに配置）

@originaiagent:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

2. Personal Access Token

GitHub で read:packages スコープ付きの PAT を発行し、NODE_AUTH_TOKEN 環境変数にセット。CI では GitHub Actions の secrets.GITHUB_TOKEN をそのまま使える。

3. npm install

npm install @originaiagent/core-master-sdk

Usage

型のみ (M2 時点で利用可)

import type { CoreProduct, CoreMallIdentifier } from '@originaiagent/core-master-sdk/types'

function render(product: CoreProduct) {
  return product.product_name
}

SDK クライアント (M3 で完成予定)

import { createCoreMaster } from '@originaiagent/core-master-sdk'

const coreMaster = createCoreMaster({
  baseUrl: process.env.CORE_API_URL!,
  internalApiKey: process.env.INTERNAL_API_KEY!,
  onError: (err, ctx) => {
    // Sentry など呼び側のエラー通知基盤に接続
    Sentry.captureException(err, {
      fingerprint: ['core-master-sdk', ctx.resource ?? '', String(ctx.statusCode ?? 0)],
    })
  },
})

// 単体取得
await coreMaster.products.get(422, { fields: ['id', 'product_name'] as const })
await coreMaster.mallIdentifiers.amazonAsinMap(['B0GR4P41HQ', 'B0GR4RQC2V'])

v0.2 の bulk API（ec-manager 適用想定）

// 複数 productId の product_costs を bulk 取得（500 件超は自動分割・並列）
const costs = await coreMaster.productCosts.listByIds([101, 102, 103])

// 各 productId の最新 cost を Map で受ける
const latestCostMap = await coreMaster.productCosts.listLatestByIds([101, 102, 103])
const cost101 = latestCostMap.get(101) // CoreProductCost | null

// 指定モール全件の mall_identifiers (deleted_at IS NULL は Core 側でフィルタ)
const rakutenIds = await coreMaster.mallIdentifiers.listByMall('rakuten', { limit: 5000 })

// 指定モール全件の mall_profitability (同上)
const profit = await coreMaster.mallProfitability.listByMall('amazon', { limit: 5000 })

v0.3 Write API (PATCH)

セットアップ

const coreMaster = createCoreMaster({
  baseUrl: process.env.CORE_API_URL!,
  internalApiKey: process.env.INTERNAL_API_KEY!,
  // PATCH 呼び出し時に X-Tool-Name が必須。default を渡すと全 patch 呼び出しに自動付与
  defaultToolName: 'ec-manager',
  defaultUserEmail: process.env.USER_EMAIL, // optional (audit_log.user_id に記録)
})

defaultToolName / opts.toolName の両方が未指定の場合、SDK は HTTP リクエスト前に CoreMasterValidationError を投げる (X-Tool-Name は server 側で必須、空送信は 400 になる)。

基本 PATCH

// products — 1 項目更新
const updated = await coreMaster.products.patch(422, {
  factory_url: 'https://factory.example.com/new',
})

// productCosts — change_reason 必須 (SDK 側で事前 validation)
await coreMaster.productCosts.patch(10, {
  change_reason: '為替改定 2026-04',
  exchange_rate: 21.5,
})

// productSpecs (product_group_id 単位のスペック)
await coreMaster.productSpecs.patch(7, { material: 'ABS', body_weight: 120 })

// productSkus (PK=TEXT、SKU code)
await coreMaster.productSkus.patch('SKU-RED-L', { variation_name: 'Red / L' })

If-Match 楽観ロック

呼び側が事前の GET で取得した updated_at (ISO 8601) を渡す。SDK は auto fetch しない。

const product = await coreMaster.products.getById(422)
try {
  await coreMaster.products.patch(
    422,
    { factory_url: 'https://factory.example.com/new' },
    { ifMatch: product.updated_at! },
  )
} catch (e) {
  if (e instanceof CoreMasterPreconditionFailedError) {
    // 他の書込に追い越された。再 fetch → マージ → 再送を行う。
  }
  throw e
}

Idempotency-Key

SDK が call ごとに crypto.randomUUID() で自動付与する (retry 間は固定されるため、指数バックオフ再送が安全)。手動で override したい場合は opts.idempotencyKey を渡す。

サーバ側で同一 key 2 回目書込は初回結果をキャッシュ返却 (meta.idempotent=true)。SDK は特別扱いせず data を透過的に返す。

PATCH retry ポリシー

GET と同等 (指数バックオフ / 5xx・429・ネットワーク系で retry、4xx は即エラー)。 Idempotency-Key が固定されるため再送で重複 UPDATE にはならない。

X-User-Email

createCoreMaster({ defaultUserEmail }) または opts.userEmail で指定。未指定は許容され、server 側 audit_log.user_id = NULL となる。

エラーハンドリング

import { CoreMasterNotFound, CoreMasterAuthError } from '@originaiagent/core-master-sdk'

try {
  await coreMaster.products.get(999999)
} catch (e) {
  if (e instanceof CoreMasterNotFound) return null
  if (e instanceof CoreMasterAuthError) throw e // env 設定ミス、silent 禁止
  throw e
}

設計書 §3.4 / §11.3.8 も参照。

Caveats (v0.3)

product_skus は last-write-wins (楽観ロック非適用)

product_skus テーブルには updated_at カラムが無いため、If-Match 楽観ロックは物理的に効かない。SDK は opts.ifMatch header をそのまま送るが、server 側で無視される (last-write-wins)。並列書込のロストアップデートを避けたい場合は、呼び側で整合性を担保すること (guide §2 D-3 / masterV1Write.ts の pkType=text 分岐参照)。

スキーマ拡張 (updated_at カラム追加) は v0.3 D-3 では migration 禁止のため v0.4 以降の課題。

鍵漏洩の爆発半径

v0.3 は read/write で同一の X-Internal-API-Key を使う (guide §3 推奨案 A)。鍵漏洩時の検知は監査ログ (audit_log_core_writes) 依存。v0.4 で書込専用鍵分離への段階移行が guide に記載済。

Development

このパッケージは origin-core monorepo の workspace として動作する。単体リリース時は packages/core-master-sdk/ 配下で操作する。

Build

# monorepo ルートから
npm run --workspace @originaiagent/core-master-sdk build

# または package ディレクトリから
cd packages/core-master-sdk
npm run build

tsup が ESM + CJS + d.ts を dist/ に出力する。

Typecheck

npm run --workspace @originaiagent/core-master-sdk typecheck

Publish (GitHub Packages)

publish は .github/workflows/publish-sdk.yml（GitHub Actions）で自動化されている。secrets.GITHUB_TOKEN (packages: write 権限) を使うため、追加の PAT 発行は不要。

手動 publish（初回 / ホットフィックス）

GitHub UI で Actions → Publish Core Master SDK → Run workflow
dry_run: true にすると npm publish --dry-run のみ実行（公開されない）
そのまま実行すると build → typecheck → dry-run → publish の順に走る

タグ連動 publish（通常リリース）

core-master-sdk-v<semver> 形式のタグを push すると自動で publish される。

# 例: 0.1.0 stable リリース
cd packages/core-master-sdk
npm version 0.1.0 --no-git-tag-version  # package.json を更新 → commit → PR → main マージ後
git tag core-master-sdk-v0.1.0
git push origin core-master-sdk-v0.1.0

タグ名を core-master-sdk-v* にしている理由: 将来 monorepo に他パッケージが追加されても衝突しないよう package 名を prefix に含める。

ローカルから手動 publish する場合

通常は不要だが、緊急時の手順:

# .npmrc に NODE_AUTH_TOKEN=<packages:write PAT> を設定しておく
npm publish --workspace @originaiagent/core-master-sdk --dry-run
npm publish --workspace @originaiagent/core-master-sdk

publishConfig.registry で npm.pkg.github.com を指定済。

Versioning

Keep a Changelog + semver。v0.x のうちは破壊的変更を minor で打てる運用。

0.1.0-alpha.1: M2 骨組み
0.1.0: Phase 1 完了 (Logi 適用、read 4 リソース)
0.2.0-alpha.1: ec-manager 適用前 bulk API 3 本追加
0.2.0: Phase 2 完了 (ec-manager 適用、bulk read 整備)
0.3.0-alpha.1: Write Support 初回 — 4 テーブル PATCH (products / product_costs / product_specs / product_skus)（本版）
0.3.0: Phase 3 完了 (HIGH 需要 3 ツール適用完了)
0.4.0: write 追加テーブル (product_attachments 等) / POST 対応 / 書込専用鍵分離
1.0.0: 既存 /api/proxy/core/* 廃止時

Architecture

origin-core monorepo 配下 packages/core-master-sdk/
型 truth source は本パッケージの src/types/public/
origin-core 本体は server/coreProducts.ts で SDK の型を 逆参照 する (設計書 §5.1.2.2)
SDK は Core に依存しない (循環禁止)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@originaiagent/core-master-sdk

Status

Install (GitHub Packages, consumers)

1. .npmrc（consumer repo のルートに配置）

2. Personal Access Token

3. npm install

Usage

型のみ (M2 時点で利用可)

SDK クライアント (M3 で完成予定)

v0.2 の bulk API（ec-manager 適用想定）

v0.3 Write API (PATCH)

セットアップ

基本 PATCH

If-Match 楽観ロック

Idempotency-Key

PATCH retry ポリシー

X-User-Email

エラーハンドリング

Caveats (v0.3)

product_skus は last-write-wins (楽観ロック非適用)

鍵漏洩の爆発半径

Development

Build

Typecheck

Publish (GitHub Packages)

手動 publish（初回 / ホットフィックス）

タグ連動 publish（通常リリース）

ローカルから手動 publish する場合

Versioning

Architecture

Links

1. `.npmrc`（consumer repo のルートに配置）