@akashic/amflow

AMFlow

Akashic Message Flow (AMFlow) は Akashic で共通に利用されるデータをやりとりするためのインターフェースを定義したものです。

このリポジトリでは、AMFlowの仕様及び、TypeScriptの型定義を提供します。

AMFlowの実装（以下、AMFlow実装）は、全てのメソッドを実装する必要はなく、用途に応じて必要なメソッドを実装してください。

仕様

エラー

AMFlowのエラーとして以下を定義しています。

エラー名	意味	通知方法
InvalidStatus	不正な状態	例外又はコールバック関数
PermissionError	必要な権限が無い	例外又はコールバック関数
NotImplemented	未実装	例外又はコールバック関数
Timeout	タイムアウト	コールバック関数
BadRequest	不正な要求	コールバック関数
RuntimeError	実行時エラー	例外又はコールバック関数
TokenRevoked	トークンが失効した	コールバック関数

AMFlow実装は、Error#name にエラー名をセットし、例外又はコールバック関数によりアプリケーションにエラーを通知する必要があります。

TokenRevoked エラー等のコールバック関数のみで通知されるエラーは、sendEvent や sendTick を行った場合に例外は発生せず、ただ呼び出しが無視されます。

open

AMFlowのセッションを開始します。

open(playId: string, callback?: (error?: Error) => void): void;

セッションの確立成否を callback で通知します。

AMFlow実装は、このメソッド呼び出し時、または呼び出し前に必要であれば通信経路の確立を行うことが望まれます。

このメソッドの呼出し後、セッションの開始が必要なメソッドの呼び出しは、open() で指定された playId に関するものとなります。

セッションの開始が必須となるメソッドは以下となります。

• close
• authenticate
• sendTick
• sendEvent
• getTickList
• putStartPoint
• getStartPoint

また、セッションの開始が必須ではないメソッドは以下となります。

• onTick
• onEvent
• putStorageData
• getStorageData

close

開始済みのAMFlowのセッションを終了します。このメソッドの呼び出しにはセッションの開始が必須です。

close(callback?: (error?: Error) => void): void;

AMFlow実装は、このメソッドの呼び出し後に open() とセッションの開始が必要なメソッド以外のメソッド呼び出しを受け付けてはなりません。

authenticate

セッションの認証を要求します。このメソッドの呼び出しにはセッションの開始が必須です。

また、このメソッドは複数回呼び出すことが可能で、権限を更新することができます。

authenticate(token: string, callback: (error: Error, permission: Permission) => void): void;

認証要求の結果として、権限情報を表す Permission を callback で通知します。

AMFlow実装は、この Permission を元にその他のメソッドの動作を制限しなくてはなりません。

詳細は、Permission.ts に定義されています。

sendTick

playlog.Tick を送信します。このメソッドの呼び出しにはセッションの開始が必須です。

sendTick(tick: playlog.Tick): void;

playlog.Tick に含まれる playlog.Event の非永続化フラグ (playlog.EventFlags.Transient) が真の場合、そのイベントは getTickList() から除外されます。

onTick

playlog.Tick の受信ハンドラを登録します。

onTick(handler: (tick: playlog.Tick) => void): void;

このメソッドは複数回呼び出され、複数の受信ハンドラが登録される可能性があります。

offTick

onTick() で登録した受信ハンドラの登録を解除します。

offTick(handler: (event: playlog.Tick) => void): void;

sendEvent

playlog.Event を送信します。このメソッドの呼び出しにはセッションの開始が必須です。

sendEvent(event: playlog.Event): void;

onEvent

playlog.Event の受信ハンドラを登録します。

onEvent(handler: (event: playlog.Event) => void): void;

このメソッドは複数回呼び出され、複数の受信ハンドラが登録される可能性があります。

offEvent

onEvent() で登録した受信ハンドラの登録を解除します。

offEvent(handler: (event: playlog.Event) => void): void;

getTickList

保存された playlog.Tick のリストを playlog.TickList の形式で取得します。このメソッドの呼び出しにはセッションの開始が必須です。

getTickList(opts: GetTickListOptions, callback: (error: Error, tickList: playlog.TickList) => void): void;

opts.begin で指定されたフレーム番号を含むフレームから、opts.end で指定されたフレーム番号を含まないフレームのリストとなります。

opts.excludeEventFlags で playlog.TickList に含まれる playlog.Event の除外条件を指定することができます。

指定された範囲の playlog.Tick が一つも見つからない場合、tickList は null となります。

putStartPoint

開始地点情報を保存します。このメソッドの呼び出しにはセッションの開始が必須です。

putStartPoint(startPoint: StartPoint, callback: (error: Error) => void): void;

StartPoint は開始地点情報を表すデータで、StartPoint.ts で定義されています。

getStartPoint

開始地点情報を取得します。このメソッドの呼び出しにはセッションの開始が必須です。

オプションとしてフレーム番号を指定しない場合は、0フレーム目に該当する開始地点情報を取得します。

オプションとしてフレーム番号を指定した場合は、フレーム番号以前の直近のフレームに該当する開始地点情報を取得します。

getStartPoint(opts: {frame?: number}, callback: (error: Error, startPoint: StartPoint) => void): void;

開始地点情報が見つからない場合、 StartPoint は null となります。

putStorageData

ストレージデータを保存します。

putStorageData(key: playlog.StorageKey, value: playlog.StorageValue, options: any, callback: (err: Error) => void): void;

getStorageData

ストレージデータを取得します。

getStorageData(keys: playlog.StorageReadKey[], callback: (error: Error, values: playlog.StorageData[]) => void): void;

インストール

npm install @akashic/amflow

利用方法

import * as AMFlow from "@akashic/amflow";

開発

ビルド

npm run build

テスト

npm test

ライセンス

本リポジトリは MIT License の元で公開されています。 詳しくは LICENSE をご覧ください。

ただし、画像ファイルおよび音声ファイルは CC BY 2.1 JP の元で公開されています。

Changelog

3.3.0

• playlog@3.3.0 に対応