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

> プロジェクトのActionを@auth0/actions NPMパッケージを使用してコーディングします。

# Actions NPM

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

### 利点

このライブラリーは以下のユースケースに役立ちます。

* **IDE / コードエディターのアシスタンス**：開発者はこのライブラリーを参照することで、IDEやコードエディターで**自動補完**、**オブジェクトと関数の定義**、**エラーチェック**を使ったコーディングを行えます。
* **TypeScript Development**：ActionはあくまでもNode.js CommonJSを使用してコーディングされ、動作しますが、このライブラリーを活用することで、**TypeScript**を使用して外部プロジェクトでActionを開発できるようになり、Auth0テナントにCommon JSとしてビルトおよびデプロイすることが可能になります。
* **ユニットテストの改善**：外部プロジェクトでのTypeScript開発が可能になることで、開発者はベストプラクティスに沿い、TypeScriptの定義に基づいて**ユニットテストを改善**できるようになります。
* **AIでのAction生成**：このライブラリーで、AIによるより正確なActionサンプルの生成に一歩近づきます。

***

### 使用方法

#### インストール

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

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

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

***

#### インポート

ライブラリーには以下の**構造**があります。

```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
```

importステートメントは、以前のライブラリー構造を考慮して、各**トリガー名**と**バージョン番号**に基づく必要があります。

**パターンに従う**：`@auth0/actions/[trigger_name]/[trigger_version]`

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

使用するテクノロジーに応じて、次のいずれかの方法でTypeScriptの定義をActionにインポートします。

既存の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">
    Use this alternative when developing with TypeScript for full type checking and modern syntax:

    ```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`ファイルにトランスパイルしてください。また、ダッシュボードでIntelliSenseを有効にするためにJSDocコメントを含める必要もあります。
</Warning>

### 例

以下のActionsの例では、JavaScriptとTypeScriptの両方を比較しやすいように横に並べています。

#### 構成

<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>

### ログイン後のアクセスコントロールとIDトークンのカスタムクレーム

以下の例のActionは、ログイン後のフロー中に実行されます。ユーザーにロールが割り当てられているかを確認し、何もない場合は`api.access.deny()`を呼び出します。ロールがある場合は、続けてIDトークンにカスタムクレームを設定します。

importステートメントは、コードで外部型が使用できることを宣言します。これにより、エディターは`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を参照してください。)

Actionsの作成について詳しくは、「[初めてのActionを作成する](/docs/ja-jp/customize/actions/write-your-first-action)」をお読みください。