📮 Address Service

The Address Service (addressService) exposes authenticated address lookup by postal code and delegates the lookup to an injected findAddressDriver. There is no built-in default driver — you must inject one (for example via createJapanPostDriver(...)) or lookups fail with the block's wrapped service error. The route schema accepts partial postal codes, but the bundled Japan Post driver ultimately requires a normalized 7-digit postal code after hyphens are removed. An optional in-memory cache can also be configured.

---

🚀 Quickstart

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

const {nodeBlocksErrorMiddleware} = middlewares;
const {addressService} = services;
const {withMongo, createJapanPostDriver} = drivers;
const {createCache} = utils;

const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');

const findAddressDriver = createJapanPostDriver(
  process.env.JAPAN_POST_CLIENT_ID!,
  process.env.JAPAN_POST_SECRET_KEY!,
  // optional third arg: hostname, default 'api.da.pf.japanpost.jp'
);

express()
  .use(
    addressService(
      {
        ...(await connectToDatabase('identities')),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        authMode: 'bearer', // or 'cookie'
        findAddressCache: createCache(),
      },
      {findAddressDriver},
    ),
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

🍪 Cookie auth: When authMode: 'cookie', protected routes read the access token from cookies. Host apps must register cookie-parser.

---

📋 Endpoint Summary

Method	Path	Description	Authorization
GET	/addresses?postalCode=...	Look up an address by Japanese postal code	Authenticated

---

🗄️ Response Shape

Successful lookups return:

{
  prefecture: string;
  city: string;
  town?: string;
  postalCode: string;
}

Field	Type	Description
prefecture	string	Prefecture name
city	string	City / municipality name
town	string	Optional town name
postalCode	string	Normalized postal code

---

🔐 Authentication Headers

Authorization: Bearer <access_token>
x-nb-fingerprint: <device_fingerprint>

The x-nb-fingerprint header is required for authenticated requests when fingerprint was specified during login.

---

🔧 API Endpoints

1. Find Address

Request:

• Method: GET
• Path: /addresses
• Authorization: Authenticated

Query Parameters:

Field	Type	Required	Description
postalCode	string	✅	Partial or full Japanese postal code (^\d{3}-?\d{0,4}$, e.g. 100 or 100-0001). If you use createJapanPostDriver, the normalized value must be 7 digits.

Response: The route returns the address object; the service sends it with Express's default JSON status (200).

Example:

curl "{{host}}/addresses?postalCode=100-0001" \
  -H "Authorization: Bearer <access-token>"

Common errors:

Status	Description
400	Validation error (missing/invalid postalCode)
401	Missing or invalid auth
404	Address not found
500	Address lookup driver failure

---

⚙️ Configuration Options

interface AddressServiceConfiguration {
  authSecrets: {
    authEncSecret: string;
    authSignSecret: string;
  };
  authMode?: 'bearer' | 'cookie';
  identity?: {
    typeIds?: {
      admin: string;
      guest: string;
      regular: string;
    };
  };
  findAddressCache?: ReturnType<typeof createCache>;
}

Datastore

Collection	Required	Description
identities	✅	Required by the service type, but not used by the address route itself

Options (third argument)

Option	Required	Description
findAddressDriver	✅ for lookups	Address lookup driver ({ findAddress(postalCode): Promise<Address> }). Use createJapanPostDriver for Japan Post. Without it, find-address requests fail.

---

🚨 Error Handling

Status	Error Message	Description
400	Validation Error	Missing or invalid postalCode query parameter
401	Authentication failure	The auth layer rejected the request
404	No matching address found.	The lookup returned no address
500	Failed to find address.	The address lookup driver failed

---

🔗 Related Documentation

• Authentication Service - Login and token management
• Identity Service - Identity lifecycle
• Error Handling - Error patterns