{"id":26093,"library":"postex-auth-sdk","title":"PostEx Auth SDK","description":"The PostEx Auth SDK (v1.3.0) provides a comprehensive authentication solution for web applications, supporting WebAuthn/passkeys, OTP, magic links, and DPoP token binding (RFC 9449). Built for PostEx ecosystem apps, it offers automatic token management, trusted device recognition, and browser feature detection. Ships TypeScript types. Release cadence: active development. Key differentiators: multi-factor with passkeys, ECDSA P-256 DPoP, and integrated session/device tracking.","status":"active","version":"1.3.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","auth","webauthn","passkey","otp","sdk","postex","typescript"],"install":[{"cmd":"npm install postex-auth-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add postex-auth-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add postex-auth-sdk","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal WebAuthn helpers for passkey registration and authentication","package":"@postex/webauthn-utils","optional":false},{"reason":"ECDSA P-256 signing for DPoP proof generation and verification","package":"@postex/crypto-utils","optional":false},{"reason":"Used for trusted device cookie management","package":"cookie","optional":false}],"imports":[{"note":"Named export, not default. ESM only; no CJS support.","wrong":"import AuthSDK from 'postex-auth-sdk-stage'","symbol":"AuthSDK","correct":"import { AuthSDK } from 'postex-auth-sdk-stage'"},{"note":"Only available with TypeScript or JSDoc type imports.","wrong":"import { config } from 'postex-auth-sdk-stage'","symbol":"AuthSDKConfig","correct":"import { AuthSDKConfig } from 'postex-auth-sdk-stage'"},{"note":"Type-only import to avoid runtime overhead.","wrong":"import { AuthStatusResponse } from 'postex-auth-sdk-stage'","symbol":"AuthStatusResponse","correct":"import type { AuthStatusResponse } from 'postex-auth-sdk-stage'"}],"quickstart":{"code":"import { AuthSDK } from 'postex-auth-sdk-stage';\n\nconst auth = new AuthSDK({\n  apiKey: process.env.POSTEX_API_KEY ?? '',\n  appId: 'postexglobal'\n});\n\nasync function login(email: string) {\n  const status = await auth.getStatus({ email });\n  const initResult = await auth.initiateAuth({ email });\n  if (initResult.status === 'webauthn_challenge') {\n    const response = await auth.authenticateWithPasskey({\n      challenge: initResult.challenge,\n      rp: initResult.rp,\n      credentialIds: initResult.credentialIds\n    });\n    console.log('Authenticated with passkey:', response);\n  } else if (initResult.status === 'otp_sent') {\n    const otpCode = await getUserOTP();\n    const verifyResult = await auth.verifyOTP(otpCode);\n    console.log('Authenticated with OTP:', verifyResult);\n  }\n}","lang":"typescript","description":"Initializes the SDK with API key and appId, checks auth status, then handles passkey or OTP based on the initiate response."},"warnings":[{"fix":"Use new AuthSDK({ apiKey, appId }) instead of new AuthSDK(apiKey, appId).","message":"Version 1.0.0 changed constructor signature: apiKey and appId moved from positional to config object.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Switch to appId: 'postexglobal' for global environment.","message":"The appId 'postex' and 'callcourier' are deprecated and will be removed in v2. Use 'postexglobal' or 'postexsa'.","severity":"deprecated","affected_versions":">=1.2.0"},{"fix":"Use auth.getStatus({ mobileNumber: '...' }) instead of auth.getStatus('...').","message":"getStatus() with a string argument must be a valid email; mobile numbers are not accepted as string. Use object form for mobile.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use auth.initiateAuth({ mobileNumber: '...' }).","message":"initiateAuth() does not accept a mobile-only identifier via string; always use object form { mobileNumber }.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use auth.authenticateMagicLink(token) instead.","message":"The method 'authenticateWithMagicLink' was renamed to 'authenticateMagicLink' in v1.1.0.","severity":"deprecated","affected_versions":"<1.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use import { AuthSDK } from 'postex-auth-sdk-stage' and ensure version >= 1.0.0.","cause":"Using a default import instead of named import, or using an older version.","error":"TypeError: auth.getStatus is not a function"},{"fix":"Use dynamic import: const { AuthSDK } = await import('postex-auth-sdk-stage'); or switch to ES modules.","cause":"Package is ESM-only and may be imported in a CommonJS context.","error":"AuthSDK is not a constructor"},{"fix":"Provide at least one identifier: auth.initiateOTP({ email: 'user@example.com' }) or { mobileNumber: '...' }.","cause":"Calling initiateOTP() without any identifier.","error":"Error: Both email and mobileNumber are missing"},{"fix":"Ensure apiKey is provided in the config and is non-empty.","cause":"apiKey is undefined or empty, causing an invalid base URL.","error":"Uncaught (in promise) TypeError: Failed to parse URL from undefined/api/..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}