NUM Client

A TypeScript/JavaScript client for the NUM protocol.

See the full Specification at the NUM Protocol Website and the Explainer for more information.

The NUM protocol supports a range of modules that add rich functionality in an extensible way.

The NUM URI Scheme

The NUM protocol uses the familiar URL format for its URIs and allows modules to interpret data in a variety of ways.

The data stored in a NUM Record is converted to JSON String format that can be parsed into JSON objects for straightforward incorporation into TypeScript and JavaScript programs. Here are some example NUM URIs with module 1 - the Contacts module. The default module is 0 (zero) if no module is specified, which has no module schema.

- num://numexample.com:1
- num://jo.smith@numexample.com:1
- num://jo.smith@numexample.com:1/work
- num://jo.smith@numexample.com:1/personal
- num://jo.smith@numexample.com:1/hobbies
- num://numexample.com:1/support
- num://numexample.com:1/support/website
- num://numexample.com:1/support/delivery
- num://numexample.com:1/enquiries
- num://numexample.com:1/sales

As you can see from the examples above, data can be associated with domains and email addresses, and can be organised hierarchically if desired. In future, the protocol will support more than just domains and email addresses.

Additional modules can be referenced in the same way as ports in other URIs:

- num://numexample.com:2 for the Registrant module.
- num://numexample.com:3 for the Images module.
- num://numexample.com:4 for the Custodians module.
- num://numexample.com:5 for the Payments module.
- num://numexample.com:6 for the Regulatory module.
- num://numexample.com:7 for the Public Key module.
- num://numexample.com:8 for the Intellectual Property module.
- num://numexample.com:9 for the Terms module.
- num://numexample.com:10 for the Bugs module.
- num://numexample.com:nn for your own module?

Adding Support for the NUM Protocol

Install using:
``shell
npm install -s num-client
`

TypeScript Examples

`typescript
const lookup = async () => {
const numUri = parseNumUri('num.uk:1'); // Parse the NUM URI
const client = createClient(); // Create a NumClient
const ctx = client.createContext(numUri); // Set the lookup context
ctx.setTargetExpandedSchemaVersion('2'); // Set the required expanded schema version (specific to each module but defaults to 1)
const result = await client.retrieveNumRecord(ctx); // Use the context to retrieve a NUM record
console.log(result); // Handle the result
}
`


Reusing the NUMClient

console.log(result[0]);
console.log(result[1]);
}
`


Overriding the Default DoH Endpoint

const client = createClient(DEFAULT_RESOLVERS); // Use a custom DoH service
// ...
};
`


Providing User Variable Values

const result = await client.retrieveNumRecord(ctx); // Use the context to retrieve a NUM record
console.log(result) // Handle the result
}
`


Using a CallbackHandler

const handler: CallbackHandler = {
setLocation: (l: NumLocation): void => {
console.log(l); // l is the Location where the result was found
},
setResult: (r: string): void => {
console.log(r); // r is the NUM record as a JSON string
},
setErrorCode: (e: string): void => {
console.log(e); // e is the error message
}
};

client.retrieveNumRecord(ctx, handler).then((_r) => {
// Ignore because the callback handler will handle it
}, (err) => console.error(err));
}
`


JavaScript Examples

num.lookup('num.uk:1').then((result) => console.log(result));
`


Full Usage

const handler = { // Provide a custom CallbackHandler
setLocation: (l) => {
console.log(l); // l is the Location where the result was found
},
setResult: (r) => {
console.log(r); // r is the NUM record as a JSON string
},
setErrorCode: (e) => {
console.log(JSON.stringify(e));
}
};

const result1 = client.retrieveNumRecord(ctx1, handler);
const result2 = client.retrieveNumRecord(ctx2, handler);

return Promise.all([result1, result2]);
}

lookup('num.uk:1', 'numexample.com:1').then((result) => {
// Ignore because the callback handler will handle the results.
});
`


HTML and JavaScript Example


``