Arkstack

Appearance

API Reference ​

This page documents Arkstack’s stable public surface across runtime drivers and generated applications.

Runtime Contracts ​

Arkstack defines runtime-agnostic boundaries in @arkstack/contract.

ArkstackKitDriver<TApp, TMiddleware> ​

Every driver package implements these required methods:

  • name
  • createApp()
  • mountPublicAssets(app, publicPath)
  • bindRouter(app)
  • applyMiddleware(app, middleware)
  • start(app, port)

Optional method:

  • registerErrorHandler(app)

ArkstackRouterContract<TApp, TRoutes> ​

  • bind(app) — binds discovered routes into the runtime.
  • list(options?, app?) — returns route metadata used by route:list.

ArkstackRouterAwareCore<TApp, TRoutes> ​

Application core implementations expose:

  • getAppInstance()
  • getRouter()

Shared Console Runtime ​

Arkstack kits use @arkstack/console to run common commands.

  • Entry: runConsoleKernel()
  • Loads app core from src/core/bootstrap.ts
  • Registers built-in base commands
  • Discovers local custom commands from src/app/console/commands/*.ts

Built-in Commands ​

Run commands through the Arkstack CLI entry (for example npx ark).

route:list ​

List all registered routes with columns:

  • method
  • path
  • handler

Options:

  • --p|path? — filter routes by path

make:controller ​

Create a new controller.

Arguments:

  • name — controller name

Options:

  • --api — generate API controller stub
  • --m|model? — attach model name
  • --force — overwrite if file exists

make:resource ​

Resource generator with grouped modes:

  • resource {name}
  • collection {name}
  • all {prefix}

Common option:

  • --force

make:full-resource ​

Generate full API resource set:

  • {prefix}Resource
  • {prefix}Collection
  • {prefix}Controller

Options:

  • --m|model?
  • --force

dev ​

Runs development mode by executing:

bash
pnpm exec tsdown --log-level silent

build ​

Runs production build by executing:

bash
NODE_ENV=production pnpm exec tsdown

Template Profiles ​

Arkstack currently provides four template aliases in create-arkstack:

  • express
  • express-lean
  • h3
  • h3-lean

Full Profiles ​

Include app scaffolding and Arkormˣ/database features.

Lean Profiles ​

Remove:

  • src/app
  • src/routes/api.ts
  • Arkormˣ/database files and dependencies

Package Surface ​

Core shared packages:

  • @arkstack/contract
  • @arkstack/common
  • @arkstack/console
  • @arkstack/http
  • @arkstack/auth
  • @arkstack/notifications
  • @arkstack/view

Driver packages:

  • @arkstack/driver-express
  • @arkstack/driver-h3

Authentication ​

@arkstack/auth exposes the framework-neutral auth service and session contracts.

Auth ​

  • Auth.make(secret?) — create an auth service instance.
  • Auth.setRequest(req) — set the current normalized request on the static auth context.
  • setRequest(req) — set the request source for the current auth instance.
  • verify(email, password) — verify credentials.
  • attempt(email, password) — authenticate and return the user or throw AuthenticationException.
  • login(email, password) — authenticate and create a personal access token.
  • authorizeToken(token) — validate a bearer token and return the authenticated user.
  • createTemporaryToken(user, purpose, expiresIn?) — create a short-lived JWT for a specific purpose.
  • authorizeTemporaryToken(token, purpose) — validate a temporary token and return its user.
  • logout(token?) — delete a specific token or the current user's tokens.
  • session() — create a Session helper for the current request.

TwoFactor ​

  • createSetup(user, secret?) — create an authenticator secret and otpauthUrl.
  • verifyCode(user, secret, code) — verify an authenticator app code.
  • setSecret(userId, secret) / getSecret(userId) / clearSecret(userId) — manage encrypted authenticator secrets.
  • setMethod(userId, method) / getMethod(userId) — manage the active 2FA method.
  • setEnabledAt(userId, enabledAt?) / getEnabledAt(userId) — manage enabled state.
  • generateBackupCodes(count?) — create printable recovery codes.
  • hashBackupCodes(codes) / writeRecoveryCodeHashes(userId, hashes) — store recovery codes.
  • consumeRecoveryCode(userId, recoveryCode) — verify and remove one recovery code.
  • issueSmsCode(user, purpose) — create, hash, and store an SMS challenge code.
  • verifySmsCode(userId, code, purpose) — verify and consume an SMS challenge code.
  • readStatus(userId) — return enabled state, method, timestamp, and remaining recovery codes.

Driver Auth Middleware ​

Express:

ts
import { auth } from '@arkstack/driver-express/middlewares';

H3:

ts
import { auth } from '@arkstack/driver-h3/middlewares';

Both middlewares expect an Authorization: Bearer <token> header.

Notifications ​

@arkstack/notifications exposes framework-neutral notification drivers.

Notification ​

  • Notification.mail(options?) / Notification.email(options?) — create a mail notification driver.
  • Notification.sms(options?) — create an SMS notification driver.
  • Notification.db() — create a database notification driver.
  • Notification.channel(channel?, options?) — create a driver from a channel or notifications.default_driver.
  • new Notification(channel, options?).prepare(recipient, data?) — prepare a driver using a user-like recipient or direct address.

Mail recipients support strings, arrays of strings, { 'address@example.com': 'Name' }, and arrays of named address objects.

Notification Config ​

  • notifications.default_driver — default channel for Notification.channel().
  • notifications.drivers.mail.transport — mail transport name, usually smtp.
  • notifications.drivers.sms.transport — SMS transport name, africastalking or twilio.
  • notifications.drivers.db.table — database notifications table name.
  • notifications.transports.smtp — SMTP connection options.
  • notifications.transports.africastalking — AfricasTalking credentials.
  • notifications.transports.twilio — Twilio credentials.

UserNotificationCenter ​

  • create(user, payload) — store a database notification.
  • forUser(user) — list stored notifications for a user.
  • unreadForUser(user) — list unread notifications for a user.
  • markAllRead(user) — mark every unread notification for a user as read.
  • markRead(notification) — mark a notification as read.
  • delete(notification) — delete a notification.

Views ​

@arkstack/view exposes Edge.js powered rendering.

view ​

  • view(name, data?) — create a renderable view instance. The result can be awaited or rendered with .render().
  • view() — return the shared view factory.
  • view().share(key, value) / view().share(data) — share data with every view rendered by the shared factory.

View ​

  • View.make(name, data?) — create a renderable view instance.
  • View.first(names, data?) — create the first existing view from a list.
  • View.exists(name) — check if a view exists.
  • View.share(key, value) / View.share(data) — share data globally.
  • View.composer(names, callbackOrComposer) — register a view composer function, class, or instance with compose().
  • View.mount(path) / View.mount(name, path) — mount view directories.
  • View.raw(name, contents) — register an in-memory Edge template.
  • Package scoped names use ~package-name.view and ~org/package-name.view.

HTTP ​

@arkstack/http exposes framework-neutral wrappers:

  • Request.from(source?)
  • request.header(name)
  • request.bearerToken()
  • request.setUser(user)
  • request.user
  • Response.from(source?)
  • response.status(code)
  • response.json(body)

Common Utilities ​

@arkstack/common exposes:

  • ErrorHandler — class-based error normalization, logging, and payload creation.
  • Exception, AppException, RequestException — shared exception classes.
  • Hash — password hashing and verification helper.
  • Encryption — encryption/decryption helper.
  • Hook — process-local hook registry with set, has, get, getAll, unset, and clear.
  • getModel(name) — typed app model resolver.
  • perPage(query) — pagination limit helper.