poe-oauth

0.0.6 verified Sat Apr 25 auth: no javascript

OAuth client and auth verification for the Poe API (v0.0.6). Provides PKCE-based OAuth flow with local callback server and API key validation. Ships TypeScript types. Release cadence: active development within the poe-code monorepo (v3.x branch). Differentiators: minimal dependencies, built-in landing page customization, and keyless identity verification via checkAuth. No alternative standalone packages exist for Poe OAuth.

Common errors

error TypeError: client.authorize is not a function ↓

cause Importing default instead of named export.

fix

import { createOAuthClient } from 'poe-oauth'

error Error: Cannot find module 'poe-oauth' ↓

cause Package not installed or not in CJS context.

fix

npm install poe-oauth and use ESM (import syntax).

error TypeError: a.readLine is not a function ↓

cause readLine callback not provided or not async.

fix

Provide an async function that returns a string for readLine.

error Error: PKCE verification failed ↓

cause Mismatched code_verifier caused by network interception or manual token paste.

fix

Ensure the token URL is called with the correct code_verifier; avoid modifying the authorization code.

Warnings

gotcha The OAuth client requires both openBrowser and readLine callbacks; providing only one will cause authorize() to hang. ↓

fix Always provide both callbacks, even if one is a no-op for your use case.

gotcha Default endpoints point to poe.com and api.poe.com; using custom endpoints requires both authorizationEndpoint and tokenEndpoint to be set together. ↓

fix If overriding one endpoint, override both to avoid mismatched flow.

deprecated The authorize() method returns an object with waitForResult(); using an older pattern that expects a direct promise is now deprecated. ↓

fix Use await client.authorize().waitForResult() instead of awaiting client.authorize() directly.

Install

npm install poe-oauth

yarn add poe-oauth

pnpm add poe-oauth

Imports

createOAuthClient

wrong

const createOAuthClient = require('poe-oauth')

correct

import { createOAuthClient } from 'poe-oauth'

ESM-only; package has no CJS export.

checkAuth

wrong

import checkAuth from 'poe-oauth'

correct

import { checkAuth } from 'poe-oauth'

Named export, not default.

type OAuthResult

wrong

const { OAuthResult } = require('poe-oauth')

correct

import type { OAuthResult } from 'poe-oauth'

TypeScript type; not a runtime value.

Quickstart

Demonstrates full OAuth flow: creating client, authorizing, waiting for callback, and verifying the API key.

import { createOAuthClient, checkAuth } from 'poe-oauth';

// Start OAuth flow
const client = createOAuthClient({
  clientId: process.env.POE_CLIENT_ID ?? '',
  openBrowser: async (url) => { console.log('Open:', url); },
  readLine: async () => { return prompt('Paste token:') ?? ''; }
});

const authorization = await client.authorize();
console.log('Authorization URL:', authorization.authorizationUrl);
const result = await authorization.waitForResult();
console.log('API Key:', result.apiKey);

// Verify token
const identity = await checkAuth({ apiKey: result.apiKey });
console.log('Identity:', identity);