> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 公式の @auth0/actions NPM パッケージを開発用依存関係としてインストールすると、外部エディターでトリガーとバージョンごとに Auth0 Actions を作成して単体テストする際に、TypeScript 型定義、IntelliSense、エラーチェックを追加できます。

# Actions NPM

[**`@auth0/actions`** NPM パッケージ](https://www.npmjs.com/package/@auth0/actions)は、**Auth0 Actions の TypeScript 型定義**を提供する**公式の Actions ライブラリ**です。これにより、外部エディターや IDE でプロジェクトの Actions をコーディングし、テストできます。

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  [**`@auth0/actions`** の公開リポジトリ](https://github.com/auth0/auth0-actions)では、この NPM パッケージの元になっているコードを参照できます。
</Callout>

<div id="benefits">
  ### 利点
</div>

このライブラリは、次のユースケースで役立ちます。

* **IDE / コードエディター支援**: このライブラリを参照することで、IDE やコードエディターは、**自動補完**、**オブジェクトや関数の定義**、**エラーチェック**などを通じて、開発者のコーディングを支援できます。
* **TypeScript 開発**: Actions は引き続き Node.js CommonJS を使って記述・実行されますが、このライブラリを使うことで、外部プロジェクトで **TypeScript** による Actions 開発が可能になり、その後 Auth0テナント向けの CommonJS としてビルドおよびデプロイできます。
* **単体テストの改善**: 外部プロジェクトでの TypeScript 開発を可能にすることで、このライブラリは、開発者がベストプラクティスに従い、TypeScript 型定義に基づいて**単体テストを改善**できるようにします。
* **AI による Actions 生成**: このライブラリにより、AI がより正確な Action の例を生成できるようになるまで、あと一歩のところまで近づきます。

***

<div id="how-it-works">
  ### 動作の仕組み
</div>

<div id="installation">
  #### インストール
</div>

以下のいずれかのパッケージマネージャーを使用して、このパッケージを**開発用依存関係**としてインストールしてください。

> このパッケージは、開発ツールを補完するため、開発用依存関係として使用する必要があります。

* **NPM**: `npm install @auth0/actions --save-dev`
* **Yarn**: `yarn add @auth0/actions --dev`
* **Pnpm**: `pnpm add @auth0/actions --save-dev`

***

<div id="import">
  #### インポート
</div>

このライブラリは次の**構成**になっています:

```bash theme={null}
@auth0/actions
│
└───credentials-exchange
│   └───v1
│   └───v2
└───custom-email-provider
│   └───v1
└───custom-phone-provider
│   └───v1
└───custom-token-exchange
│   └───v1
└───event-stream
│   └───v1
└───password-reset-post-challenge
│   └───v1
└───post-change-password
│   └───v1
│   └───v2
└───post-login
│   └───v1
│   └───v2
│   └───v3
└───post-user-registration
│   └───v1
│   └───v2
└───pre-user-registration
│   └───v1
│   └───v2
└───send-phone-message
    └───v2
```

インポート文は、以前のライブラリ構造を踏まえ、各**トリガー名**と**バージョン番号**に基づいて指定する必要があります。

**次のパターンに従ってください**: `@auth0/actions/[trigger_name]/[trigger_version]`

**例**: `@auth0/actions/post-login/v3`

利用している技術に応じて、次のいずれかの方法で TypeScript の型定義を Actions にインポートしてください。

既存の JavaScript コード構造を変更せずに IntelliSense を利用したい場合は、この方法を使用します。

<Tabs>
  <Tab title="JSDoc @import">
    既存の JavaScript コード構造を変更せずに IntelliSense を利用したい場合は、この方法を使用します。

    ```javascript theme={null}
    /** @import {Event, PostLoginAPI} from "@auth0/actions/post-login/v3" */

    /**
    * PostLogin フローの実行中に呼び出されるハンドラー。
    *
    * @param {Event} event - ユーザーに関する詳細情報と、ログイン時のコンテキスト。
    * @param {PostLoginAPI} api - ログインの挙動を変更するためのメソッドを提供するインターフェース。
    */
    exports.onExecutePostLogin = async (event, api) => {
      // コードを記述
    }
    ```
  </Tab>

  <Tab title="JSDoc @param">
    JSDoc コメント内の import 文を使って、JavaScript ファイルで型安全性を確保したい場合は、この方法を使用します。

    ```javascript theme={null}
    /**
    * PostLogin フローの実行中に呼び出されるハンドラー。
    *
    * @param {import('@auth0/actions/post-login/v3').Event} event - ユーザーに関する詳細情報と、ログイン時のコンテキスト。
    * @param {import('@auth0/actions/post-login/v3').PostLoginAPI} api - ログインの挙動を変更するためのメソッドを提供するインターフェース。
    */
    exports.onExecutePostLogin = async (event, api) => {
      // コードを記述
    };
    ```
  </Tab>

  <Tab title="TypeScript import">
    TypeScript で開発し、完全な型チェックとモダンな構文を利用したい場合は、この方法を使用します。

    ```javascript theme={null}
    import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

    /**
    * PostLogin フローの実行中に呼び出されるハンドラー。
    *
    * @param {Event} event - ユーザーに関する詳細情報と、ログイン時のコンテキスト。
    * @param {PostLoginAPI} api - ログインの挙動を変更するためのメソッドを提供するインターフェース。
    */
    exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
      // コードを記述
    };
    ```
  </Tab>
</Tabs>

<Warning>
  TypeScript を使用する場合は、Auth0 にデプロイする前にコードを JavaScript にコンパイルする必要があります。Auth0 Actions ランタイムが実行できるのは JavaScript のみです。デプロイ前に、TypeScript コンパイラ (`tsc`) を使用して `.ts` ファイルを `.js` ファイルにトランスパイルしてください。また、Dashboard で IntelliSense を有効にするには、JSDoc コメントも含める必要があります。
</Warning>

<div id="examples">
  ### 例
</div>

以下のActionsの例は、JavaScriptとTypeScriptを並べて直接比較できるよう、あえて両方で示しています。

<div id="configuration">
  #### 設定
</div>

<Tabs>
  <Tab title="JavaScript">
    `package.json` では、Action の作成時に IntelliSense の支援を受けられるよう、開発用の依存関係を定義します。

    ```javascript theme={null}
    {
      "name": "actions-js",
      "version": "1.0.0",
      "description": "Actions JS",
      "main": "example.js",
      "author": "John Doe",
      "license": "ISC",
      "devDependencies": {
        "@auth0/actions": "^0.7.1"
      }
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    `package.json` では、Action の作成時に IntelliSense の支援を受けられるよう、開発用の依存関係を定義します。

    ```typescript theme={null}
    {
      "name": "actions-ts",
      "version": "1.0.0",
      "description": "Actions TS",
      "main": "example.ts",
      "author": "John Doe",
      "license": "ISC",
      "devDependencies": {
        "@auth0/actions": "^0.7.1",
        "@types/node": "22.14.0",
        "typescript": "^5.9.2"
      }
    }
    ```

    `tsconfig.json` では、Action の作成時に IntelliSense の支援を受けられるよう、必要な設定を定義します。

    ```typescript theme={null}
    {
      "compilerOptions": {
        "target": "ES2020",
        "module": "NodeNext",
        "moduleResolution": "nodenext",
        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true,
        "strict": true,
        "outDir": "dist",
        "declaration": true,
        "sourceMap": true,
        "allowJs": true,
        "checkJs": false,
        "resolveJsonModule": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "isolatedModules": true
      },
      "include": [
        "**/*.ts"
      ],
      "exclude": [
        "node_modules",
        "dist"
      ]
    }
    ```
  </Tab>
</Tabs>

<div id="post-login-access-control-and-id-token-custom-claims">
  ### Post-Login のアクセス制御と ID トークンのカスタムクレーム
</div>

次の Action の例は、Post-Login フロー中に実行されます。ユーザーにロールが割り当てられているかどうかを確認し、ロールが見つからない場合は `api.access.deny()` を呼び出します。ロールがある場合は、ID トークンにカスタムクレームを設定します。

// インポート文は、外部の型をコード内で利用できることを宣言するものです。これにより、エディターは `event` オブジェクトと `api` オブジェクトの構造を認識できます。

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    /** @import {Event, PostLoginAPI}from "@auth0/actions/post-login/v3" */

    const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

    /**
    * PostLogin フローの実行中に呼び出されるハンドラー。
    *
    * @param {Event} event - ユーザーの詳細情報と、そのユーザーがログインしているコンテキスト。
    * @param {PostLoginAPI} api - ログインの動作を変更するためのメソッドを利用できるインターフェース。
    */
    exports.onExecutePostLogin = async (event, api) => {
      const roles = event.authorization?.roles;

      if (roles === undefined || roles.length === 0) {
        api.access.deny('Restricted');
        return;
      }

      api.idToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

    const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

    /**
    * PostLogin フローの実行中に呼び出されるハンドラー。
    *
    * @param {Event} event - ユーザーの詳細情報と、そのユーザーがログインしているコンテキスト。
    * @param {PostLoginAPI} api - ログインの動作を変更するためのメソッドを利用できるインターフェース。
    */
    exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
      const roles = event.authorization?.roles;

      if (roles === undefined || roles.length === 0) {
        api.access.deny('Restricted');
        return;
      }

      api.idToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
    };
    ```
  </Tab>
</Tabs>

@auth0/actions について詳しくは、[https://www.npmjs.com/package/@auth0/actions](https://www.npmjs.com/package/@auth0/actions) をご覧ください。

`@auth0/actions` の実装コードについて詳しくは、[Auth0 Actions リポジトリ](https://github.com/auth0/auth0-actions)をご覧ください。

Actions の記述方法について詳しくは、[Write Your First Action](/docs/ja-jp/customize/actions/write-your-first-action) を参照してください。