Sess

Sess SDK

サーバーから人に質問し、検証済みの回答を受け取って処理を続けられます。

作成して実行する小さなエージェント：

npm create @sess.si/agent@latest my-agent

表示される内容： Sess リンクです。スマートフォンで2つの質問に回答すると、検証済みのレシートとともにプランがターミナルに表示されます。

独自のサーバープロジェクトに SDK をインストールします：

npm install --save-exact @sess.si/[email protected]

人に質問する

Sess 開発者ポータルの開発者 API キーを使用します。キーはサーバー上に保管してください。 アカウント登録不要のホスト型デモは別のトライアルフローです。Sess リンクやトライアル用認証情報は、所有者用 API キーではありません。LLM、エージェントフレームワーク、Docker、Sess ソースのチェックアウトは必要ありません。

import { Sess } from '@sess.si/sdk';
const sess = new Sess({ apiKey: process.env.SESS_API_KEY });
const question = await sess.ask({
  question: 'Approve the synthetic refund?',
  fields: [
    { name: 'approved', label: 'Approve it', type: 'boolean' },
    { name: 'amount', label: 'Refund amount', type: 'number', minimum: 0 },
  ],
});
console.log(`Send this Sess link to the person: ${question.link}`);
const { approved, amount } = await question.answer(); // verified; the Session is now complete
if (approved) console.log(`Refund of ${amount.toFixed(2)} approved.`);

sess.ask() は質問をローカルで検証し、Session を一度だけ作成して、待機を開始する前に Sess リンクを返します。このリンクはベアラー機能です。本人にのみ届け、ログや分析データには決して含めないでください。answer() は本人を待ち（デフォルトでは10分間）、署名付きレシートを正確な質問に照らして検証し、回答が現在のステップに対するものであることを確認して、Session を完了し、入力されたフィールド値を返します。完了すると Session は終了し、リンクから回答を送信できなくなります。フィールド型は text、number、integer、boolean、choice、multi_choice、rating です（API リファレンス）。

待機がタイムアウトした場合（wait_ended、コード WAIT_TIMEOUT）、または待機を中止した場合も、リモート側の状態は変わりません。同じハンドルで answer() を再度呼び出してください。outcome: "unknown" を含むエラーは、完了が確認されていないことを意味します。answer() を再度呼び出すと、同じ完了処理が再試行されます。ハンドルはメモリ内にのみ保持されます。再起動後に再開するには、sessionId と revision を保存し、以下の API を使って続行してください（インテグレーション）。

Sess が呼び出しを拒否すると、エラーに何が起きたか、どうすればよいかが示されます。Sess が受け付けないキーを指定すると、「Sess did not accept your API key. Check SESS_API_KEY and the portal you made it on.」と表示されます。メッセージの後にコードとリクエスト ID が続きます：

try {
  const question = await sess.ask({
    question: 'Approve the synthetic refund?',
    fields: [{ name: 'approved', label: 'Approve it', type: 'boolean' }],
  });
  console.log(`Send this Sess link to the person: ${question.link}`);
} catch (error) {
  console.error(error.message); // what happened and what to do
  const request = error.requestId ? `, request ${error.requestId}` : '';
  console.error(`Details: ${error.code ?? error.kind}${request}`);
  process.exitCode = 1;
}

短く保つ

本人はスマートフォンでページを読むため、Sess ではすべての要素を短く保ちます。長さは文字数（Unicode コードポイント）で数え、Sess が切り詰めることはありません：

内容	スタイル	最大文字数
タイトル（question）	質問またはタスク。40文字程度	80
ボタン（submit_label）	動詞。1～3語	24
フィールドラベル、選択肢	短くする	60
ヘルプ（フィールドの description）	ヒントを1つ	160
タイトル下の説明	1～2文	280
見出し	短くする	60
レコードのキャプション	数語	200
レコードのキー／文字列値	記載どおり	40 / 200
テキスト（details）	プレーンテキスト	4,000

ボタンは最大5個です。上限を超える値は、その値を示す SessError になります。field は /question などの JSON ポインター、limit は許容される最大値、length は実際の長さです。エラーメッセージには修正方法が示されます。タイトルの場合は「The title can be at most 80 characters. Keep it to a short heading, about 40.」、それ以外の場合は、たとえば「/fields/0/label is 72 characters; the limit is 60. Shorten it to at most 60 characters.」です。何も作成されていないため（outcome は not_sent または rejected）、値を短くして再度呼び出してください：

import { Sess, SessError } from '@sess.si/sdk';
declare function shorten(text: string, max: number): Promise<string>; // e.g. your model rewrites it

const sess = new Sess({ apiKey: process.env.SESS_API_KEY });
const fields = [{ name: 'approved', label: 'Approve it', type: 'boolean' }] as const;
async function askShort(question: string) {
  try {
    return await sess.ask({ question, fields });
  } catch (error) {
    if (!(error instanceof SessError) || error.field !== '/question' || error.limit === undefined)
      throw error;
    return sess.ask({ question: await shorten(question, error.limit), fields });
  }
}

リリース状況： 現在のリリースは 0.2.0 で、latest dist-tag で提供されています。このリリースでは、sess.ask に評価フィールドと回答者が追加されています。next は引き続き前回のリリース候補である 0.1.0-rc.10 を指します。変更履歴に各バージョンの説明があります。npm view @sess.si/sdk dist-tags で、現在レジストリから提供されている内容を確認できます。

コマース

Sess は決済を受け付けません。利用者は Sess のページで請求内容を承認し、資金の移動はお客様と決済プロセッサーが担います。

import { Sess, invoice } from '@sess.si/sdk';
const sess = new Sess({ apiKey: process.env.SESS_API_KEY });
const created = await sess.sessions.create({
  interaction: invoice({
    currency: 'CAD', // whole cents: 420000 is $4,200.00
    reference: 'INV-2041',
    rows: [{ name: 'Design retainer, October', amount: 420000 }],
    lines: [{ label: 'GST 5%', amount: 21000, role: 'tax' }],
  }),
});
console.log(`Send this Sess link to the person: ${created.data.human_url}`);

最初に押さえておきたい点は、次の3つです。

• 短い行。 行名は最大80文字、詳細は最大160文字です。長すぎる値は切り詰めずに拒否されます。SessError は /interaction/source/components/1/rows/0/name のようなポインターで対象を示し、limit と length も含みます。
• 通貨の最小単位を整数で指定。 金額は通貨の最小単位で整数として指定します。USD はセント、JPY は円、BHD はフィルスです。money(1250, 'USD') は $12.50 ですが、money(12.5, 'USD') はエラーになります。Sess が丸めたり換算したりすることはありません。
• 合計は正確に。 ビルダーは行と明細から小計、合計、支払額を計算します。手書きの items コンポーネントで、小計が行の合計と一致しない場合は、HTTP 400 で拒否されます。

{
  "error": {
    "code": "INVALID_SCHEMA",
    "field": "/interaction/source/components/0/totals/0/amount",
    "expected": 441250,
    "actual": 451248
  }
}

invoice()、receipt()、quote()、refund()、purchaseOrder() はそれぞれ、sess.sessions.create({ interaction }) で使える通常のインタラクティブな Surface を返します。請求内容は items カードとして表示され、ドキュメントの reference は装飾のない名前で表示されます。また、利用者に必要なボタン（Approve と Decline、レシートでは Continue、見積もりでは Accept）も用意されます。refund() は「Refund total」の下に正の金額を表示します。行に quantity を指定すると、利用者が数量を変更できるようになり、「Request changes」ボタンが追加されます。エージェントは新しいリビジョンと更新後の金額で応答します。items() はカードだけを作成し、lintText() はテキスト内の Markdown テーブルを検出します。利用者にはパイプ記号として表示されます。API リファレンスをご覧ください。

Sess が行わないこと：決済の受け付けや資金の移動、通貨換算、税額や価格の計算、ロゴやブランディングの表示、別のサイトによるページのフレーム表示（frame-ancestors 'none'）。

上級者向け：Surface API の全機能

import { Sess } from '@sess.si/sdk';

const sess = new Sess({ apiKey: process.env.SESS_API_KEY });
const created = await sess.sessions.create({
  interaction: {
    mode: 'interactive',
    title: 'Review a synthetic invoice',
    source: {
      kind: 'sess_surface',
      components: [
        { type: 'record', label: 'INV-001', fields: { amount: 120 } },
        {
          type: 'field',
          name: 'amount',
          label: 'Correct amount',
          required: true,
          schema: { type: 'number', minimum: 0 },
          value: 120,
        },
      ],
    },
    actions: [{ id: 'submit', label: 'Submit review', intent: 'submit' }],
  },
});

// Privately deliver created.data.human_url through your application's handoff.
// It is a bearer capability: do not put it in ordinary logs or analytics.
const answer = await sess.sessions.waitForResponse(created.data.id, {
  revision: created.data.revision,
});
const verified = await sess.receipts.verifyResponse({
  sessionId: created.data.id,
  response: answer.response,
});
const amount = verified.response.data.amount;
if (typeof amount !== 'number' || !Number.isFinite(amount)) {
  throw new Error('Expected an accepted numeric amount');
}

検証では、レシートがご利用のワークスペース向けに発行されたことを確認します。認証済みのレスポンスにはワークスペース名が含まれる（Sess-Workspace-Id ヘッダー）ため、お客様側で設定する必要はありません。ランタイムがこのヘッダーを送信しない場合は、信頼できるデプロイ設定から expectedWorkspaceId を設定してください。設定しないと、VERIFICATION_CONTEXT_MISSING で検証に失敗します。SDK は、未検証のレシートからワークスペースを取得することはありません。

クイックスタート関数には、非公開の配信コールバックが含まれています。 3ラウンドの継続では、変更の意図を永続化し、回答を公開または完了する前に、それが現在想定されているビジネス上のステップに対応していることを確認します。ストアとワーカーレースはアプリケーション側で管理します。統合ガイドをご覧ください。

意思決定バンドルを確認する

意思決定バンドルとは、所有者が共有を選択した、承認済みの1つの意思決定のことです。署名済みレシート、正確な Surface と入力内容、発行者の公開鍵が含まれます。信頼できる鍵を使い、ご自身のコンピューターで確認してください（バンドル内の鍵は使用しないでください）。

npx -p @sess.si/[email protected] sess verify bundle.json --issuer https://api.sess.si --keys sess-receipt-keys.json

sess コマンドは 0.1.0-rc.5 で初めてリリースされます。これ以降のバージョン（0.2.0 を含む）では利用できます。

Valid decision bundle. と、承認された内容、日時、リビジョンが表示されます。無効な場合は Invalid と最初の理由が表示されます。終了ステータスは、有効な場合は0、無効な場合は1、使用方法のエラーの場合は2です。完全な結果を表示するには --json を追加してください。データが外部に送信されることはありません。コードからは、@sess.si/sdk/receipts の verifyDecisionBundle を使用します（セキュリティ）。形式については、receipt-v1 と bundle-v1 をご覧ください。

リンクを QR コードで表示する

相手がノート PC を使っていて、スマートフォンで回答する場合は、ネットワーク通信を行わず、ローカルでリンクを QR コードとして表示します。

import { printQr, qr } from '@sess.si/sdk/qr';

const link = 'https://sess.si/s/synthetic-link'; // the link sess.ask() returned
console.log(link);
printQr(link); // prints "Scan to answer on your phone" and the code, on an interactive terminal only
const svg = qr(link, { format: 'svg' }); // also 'png' (bytes) and 'terminal' (text)

画面は見えていてもスマートフォンは見えない場合に使用します。デスクトップのチャットウィンドウ、ダッシュボード、キオスク、印刷物などが該当します。SMS では使わず、相手がすでにスマートフォンを使っている場合も表示しません。Sess がコードを表示したり送信したりすることはありません。表示するかどうかはエージェントが判断します。printQr は、TTY がない場合、CI 環境（CI が設定されている場合）、本番環境（NODE_ENV=production の場合）、--no-qr が指定されている場合、または { qr: false } が指定されている場合は何も出力せず、NO_COLOR が設定されている場合は色なしで表示します。コードはプライベートリンクを別の形式にしたものです。リンクと同じように適切に管理し、ログ、分析データ、URL には決して含めないでください。

ランタイムとインポート

サポート対象：メンテナンス中の Node 22 のうち 22.14 以上、および Node 24（推奨）。 TypeScript の利用者向け型宣言は 5.9 と最新の安定版を対象としています。JavaScript の利用者にコンパイラーは不要です。 パッケージには ESM ビルドが 1 つ含まれています。CommonJS アプリケーションでは、CommonJS の例のように await import('@sess.si/sdk') を使用します。同期的な require はサポート対象の契約ではありません。

エントリーポイントは @sess.si/sdk、@sess.si/sdk/receipts、@sess.si/sdk/webhooks、@sess.si/sdk/qr です。SDK のインポートや構築によって、サービスへの接続、サーバーの起動、認証情報ファイルの読み込み、データのログ出力が行われることはありません。

エラーと再試行

エラーは SessError で、該当する場合は安定した kind、API の code、status、requestId、attempts、書き込みの outcome フィールドを含みます。デフォルトのエラーには、サーバーのレスポンス本文とリクエストの秘密情報は含まれません。

セッションの作成は 1 回だけ試行されます。結果が不明な場合、プライベート URL が失われたもののセッションは作成されている可能性があります。自動的に再作成しないでください。有効な作成レスポンス本文を受信したもののヘッダーに問題がある場合は、error.getRecoveryResult() を明示的に調べ、その機能を適切に保護してください。

公開と完了には、強い引用符付きの ifMatch が必要です。永続的な書き込みを行う前に、本文、元の ETag、明示的な idempotencyKey を保存してください。内部再試行では、これらの値と解決済みの認証情報がそのまま維持されます。409 または 412 は呼び出し元に返されます。SDK が書き込みを強制するために ETag を更新することはありません。

直接 HTTP も引き続きサポートされています

SDK を使わずに、同じ作成操作を利用できます。

curl --request POST https://api.sess.si/v1/sessions \
  --header "Authorization: Bearer $SESS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @interaction.json

ここで interaction.json には、同じ { "interaction": ... } リクエスト本文が含まれます。レスポンスには人間向けのプライベート URL が含まれるため、ターミナル出力を保護し、リクエストのトレースを無効にしてください。完全な仕様は OpenAPI で確認できます。

ガイド

• API リファレンス：サポート対象の操作、検証済みレスポンス、オプション、エラー。
• インテグレーション：作成、ライフサイクル、検証、永続性、今後の拡張範囲。
• セキュリティ と レシートの例。
• Webhooks と 永続的な受信箱との境界を設けた Node の受信側。
• 互換性、レジストリパッケージへの移行、リリース手順書。
• Plain-Node クイックスタート：最初の呼び出しから回答の検証までを網羅した完全なプログラム。

Sess が相手に表示するページを描画します。この SDK に外観設定はありません。

貢献 · セキュリティに関する報告 · Apache-2.0