🏠 Address

Address provides an authenticated Japanese postal-code lookup service backed by a host-supplied findAddressDriver.

Start here

import {drivers, services} from '@nodeblocks/backend-sdk';

const findAddressDriver = drivers.createJapanPostDriver(
  process.env.JAPAN_POST_CLIENT_ID!,
  process.env.JAPAN_POST_SECRET_KEY!,
);

app.use(
  '/api',
  services.addressService(
    {identities},
    {authSecrets: {authEncSecret: 'replace-me', authSignSecret: 'replace-me'}},
    {findAddressDriver},
  ),
);

Configuration	Default / source behavior	Effect
authSecrets	Required; passed to the selected authentication utility	Verifies access tokens.
authMode	Omitted or 'bearer' selects Bearer tokens	'cookie' selects cookie authentication.
identity.typeIds	Passed through configuration unchanged when supplied	Not consumed by the Address route.
findAddressCache	No cache when omitted	Caches addresses by normalized postal code.
findAddressDriver option	Required for lookup; defaults to undefined	Provides findAddress(postalCode).

Common tasks

Task	Start with	Contract
Look up an address	findAddressFeature	findAddressFeature and findAddressRoute
Build a Japan Post driver	createJapanPostDriver	createJapanPostDriver
Reuse address request definitions	Address schemas	Address schemas
Mount the lookup service	addressService	addressService with a findAddressDriver option

Bearer HTTP workflow

With omitted authMode or authMode: 'bearer', send a valid access token and a query value accepted by findAddressSchema:

ADDRESS_API='https://api.example.test'
ACCESS_TOKEN='replace-with-a-valid-access-token'

curl "$ADDRESS_API/addresses?postalCode=100-0001" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

findAddressRoute returns the address JSON object with Express's default 200 status. The selected Bearer adapter can reject authentication with 401; an absent address maps to 404. User access-token security checks use the request verification data required by the configured/default authentication utility.

Cookie HTTP workflow

Configure authMode: 'cookie' and register cookie-parser before mounting the service. Send the same required query parameter with the access-token cookie established by the Authentication service:

ADDRESS_API='https://api.example.test'
ACCESS_TOKEN='replace-with-a-valid-access-token'

curl "$ADDRESS_API/addresses?postalCode=100-0001" \
  --cookie "accessToken=$ACCESS_TOKEN"

The endpoint, request schema, response, and 404 behavior are unchanged. A missing or invalid cookie is rejected by the cookie authentication adapter; see Authentication for the token-cookie setup.

Custom feature composition

findAddressFeature is a schema-and-route composer. This fragment shows the source-equivalent service context required to mount it without addressService:

import {partial} from 'ramda';
import {features, primitives, utils} from '@nodeblocks/backend-sdk';

const router = primitives.defService(
  partial(primitives.compose(features.findAddressFeature), [
    {
      authenticate: utils.getBearerTokenInfo,
      configuration,
      dataStores: {identities},
      findAddressDriver,
    },
  ]),
);

app.use('/api', router);

The fragment requires configuration.authSecrets, the identities collection, and a findAddressDriver; use findAddressRoute and findAddressSchema for the endpoint contract.

Reference map

Page	Purpose
Blocks	Lookup contract, errors, and public types.
Features	Schema-to-route composition.
Routes	The protected address endpoint.
Schemas	Reusable address data and lookup request schemas.
Validators	Shared authentication requirement.

The Address service is the mountable integration surface for this category.

Related modules

Japan Post driver supplies the lookup implementation. Authentication documents token transport used by this protected route.