Township Auth Client

Common errors

• TypeError: TownshipClient is not a constructor

  cause Attempting to instantiate `TownshipClient` when it's not correctly imported as a constructor, often due to mismatched CommonJS/ESM import styles or transpilation issues.
  fix For CommonJS, use `const TownshipClient = require('township-client'); const client = TownshipClient(...)`. If using ESM, and if the package has a default export compatible with `esModuleInterop`, `import TownshipClient from 'township-client'` might work, otherwise `import * as TownshipClient from 'township-client'; const client = TownshipClient.default(...)` may be necessary.

• Error: Server connection failed

  cause The configured `opts.server` URL is incorrect, the Township server is unreachable, or there is a general network connectivity issue.
  fix Verify that the `server` URL passed to `TownshipClient` initialization is correct and the target Township authentication server is operational and accessible from the client's network environment.

• Register error Error: {"message":"email already exists"}

  cause An attempt was made to register a user with an email address that is already associated with an existing account on the Township server.
  fix Use a unique email address for new user registration or attempt to log in if the user is already expected to exist.

• Login error Error: {"message":"Invalid credentials"}

  cause The provided email or password for login does not match any registered user on the configured Township server.
  fix Double-check the email and password for typos. If the password is forgotten, the library's `changePassword` method can be used, but requires a valid login token for the user already to be saved.

Warnings

• breaking The `township-client` library and its associated `township` server project appear to be abandoned, with no significant development activity since around 2017. This implies no further updates, bug fixes, or security patches will be provided.
  Fix: Consider migrating to a actively maintained authentication solution. Using this library in new projects is not recommended due to unaddressed security vulnerabilities and lack of support.
• gotcha The library relies on outdated versions of underlying HTTP clients (like `nets`), which may contain known security vulnerabilities, lack modern features, or have performance issues compared to contemporary alternatives.
  Fix: Audit project dependencies for known CVEs. If external audits are not feasible, consider wrapping the library's network calls with a more modern and secure HTTP client, or migrating away from this library entirely.
• gotcha Primarily designed for CommonJS (`require`) environments, integrating this library into modern ES Module (`import`) projects might require specific build configurations (e.g., `esModuleInterop` in TypeScript) or result in compatibility issues.
  Fix: If using in an ESM project, explicitly configure your build tools (like Webpack, Rollup, or TypeScript compiler) to handle CommonJS modules, or use dynamic `import()` for the module.
• gotcha The library does not ship with TypeScript type definitions. Developers using TypeScript will need to create their own declaration files (`.d.ts`) to achieve type safety or use it as a dynamically imported JavaScript module.
  Fix: Manually create a `township-client.d.ts` file with basic type declarations for the `TownshipClient` constructor and its methods, or use `@ts-ignore` for untyped imports (not recommended for production).

Install

• npm install township-client npm
• yarn add township-client yarn
• pnpm add township-client pnpm

Imports

• TownshipClient
  wrong:

  import TownshipClient from 'township-client'

  correct:

  const TownshipClient = require('township-client')

  The library is primarily designed for CommonJS (`require`) environments. While ES Module imports might work with transpilers or `esModuleInterop`, the original intent is CJS.
• client.register

  client.register({ email: '...', password: '...' }, callback)

  Registers a new user with the specified email and password, receiving a token upon success.
• client.login

  client.login({ email: '...', password: '...' }, callback)

  Logs in an existing user with the provided credentials, persisting login information to the configured file or localStorage.

Quickstart

Initializes the TownshipClient, registers a new user with example credentials, and then attempts to log that user in, demonstrating the basic authentication flow and login persistence.

const TownshipClient = require('township-client');

const client = TownshipClient({
  server: 'https://api.township.site', // Set default server on init
  config: {
    filename: '.townshiprc' 
    // config file stored in user homedir. 
    // uses localstorage if in browser
  }
});

client.register({
  email: 'joe@hand.email',
  password: 'Iheartcoffee'
}, function (err, res, body) {
  if (err) return console.error('Register error', err);
  console.log('Registered successfully with ', body.key, body.token);

  client.login({
    email: 'joe@hand.email',
    password: 'Iheartcoffee'
  }, function (err, res, body) {
    if (err) return console.error('Login error', err);
    console.log('Logged in successfully!');
    console.log('User login info:', client.getLogin());
  });
});