@forjio/sdk

Shared TypeScript SDK for the Forjio commerce suite.

Consumed by every product repo: huudis, plugipay, storlaunch, fulkruma, ripllo, malapos, suppuo.

What's in here

| Module | Purpose | |---|---| | @forjio/sdk/auth | JWT verification middleware (JWKS cache + ES256), OIDC client helpers. | | @forjio/sdk/arn | ARN parser + builder. forjio:<service>:<region>:<accountId>:<type>/<id> (see ADR-0008). | | @forjio/sdk/events | Event envelope type + ULID event ID generation + outbox helpers (write event inside transaction, read unpublished batch, mark published). | | @forjio/sdk/http | Response envelope type { data, error, meta }, shared validators. | | @forjio/sdk/iam | Policy evaluator, canned policy loader, condition key set. Implements the AWS-IAM-JSON policy language defined in ADR-0003. |

Install

npm install @forjio/sdk

Example: verify a Huudis JWT in an Express route

import { verifyAccessToken } from '@forjio/sdk/auth';

app.use(async (req, res, next) => {
  const token = req.headers.authorization?.replace(/^Bearer /, '');
  if (!token) return res.status(401).json({ error: { code: 'AUTH_REQUIRED' } });
  try {
    req.auth = await verifyAccessToken(token, {
      issuer: 'https://huudis.com',
      audience: 'plugipay',
    });
  } catch (err) {
    return res.status(401).json({ error: { code: 'INVALID_TOKEN' } });
  }
  next();
});

Example: emit an outbox event inside a Prisma transaction

import { writeOutboxEvent } from '@forjio/sdk/events';

await prisma.$transaction(async (tx) => {
  const session = await tx.checkoutSession.update({
    where: { id },
    data: { status: 'completed' },
  });
  await writeOutboxEvent(tx, {
    type: 'plugipay.checkout.completed.v1',
    accountId: session.accountId,
    data: { sessionId: session.id, amount: session.amount, currency: session.currency },
  });
});

Versioning

Semver. Breaking changes bump major. Products upgrade on their own cadence. Published on every merge to master.

Non-goals

• Not a business-logic library. Service-specific logic lives in each product repo.
• Not a Prisma schema share. Each service owns its own schema (see ADR-0001).
• Not an auto-generated REST client. We use handwritten thin clients with shared types — better DX than OpenAPI codegen at our scale.