@kalyptos/bifrost 0.0.0-stage → 5.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kalyptos
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @kalyptos/bifrost
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript client for the Bifrost API. Full reference: <https://bifrost.kalyptos.io/docs>.
+
+ESM with no runtime dependencies. It needs a global `fetch` (Node 18 or later, or a browser).
+
+```sh
+npm install @kalyptos/bifrost
+```
+
+## Calls
+
+```ts
+import { Bifrost } from '@kalyptos/bifrost';
+
+const bifrost = new Bifrost({ baseUrl: 'https://bifrost.example.com' });
+
+const { matches } = await bifrost.resolve({ input: 'Rådhuspladsen 1, København' });
+```
+
+`resolve`, `search` and `project` take one request and return one result, or take an array and
+return a batch. A batch item that fails is still a result: `{ input, matches: [], error }`.
+`token` is optional: a string, or a function that gives the token for each request. A response that
+is not 2xx throws `BifrostError` with `status` and `detail`.
+
+## Compose
+
+`compose` sends several calls as one `POST /compose`. Later calls read earlier outputs, and the
+result has the shape the callback returns:
+
+```ts
+const rows = await bifrost.compose((q) =>
+	q.search({ input: 'Vestergade', target: 'street', limit: 8 }).matches.map((s) => ({
+		street: s.result,
+		kommune: q.project({ input: s.ref, target: 'kommune' }).matches[0].result
+	}))
+);
+// rows: { street: string; kommune: string | undefined }[]
+```
+
+The callback runs once, synchronously, and only records. `q` calls and the values you reach from
+them are handles: paths into outputs that do not exist yet, not data.
+
+- Return a step, any path into one, a `map`, or a record of these, nested freely. A path that finds
+  nothing gives `undefined`, so its type adds `undefined` once it indexes an array or passes an
+  optional or null field.
+- A handle fits a plain string field (`input`, a `components` value, a ref `id`), not `target`,
+  `kind` or a number. A handle to a number fits only a search `input` and a ref `id`. A project
+  `input` also takes a whole ref, a match's `m.ref` or a project output's `input`, and
+  `m.refs.<kind>`, which sends that kind with the id.
+- Every match's `ref` is a `Ref`, except from a `stednavn` search: a named place is no project
+  input. With a `target` that is not a literal, narrow on `ref.kind` first.
+- `map` runs its callback once for each element on the server. The callback can make `q` calls and
+  return anything from the element or from those calls, but one call cannot feed another. If it
+  returns one of its own calls, `map` gives that step over the whole array, and you can `map` it
+  again. Returning a step made outside the callback throws. A `map` cannot nest.
+- A failed call is an empty result with `error`, for example `"unresolved reference"` when a handle
+  found nothing to send. A `map` over a path that is not an array gives `[]`.
+- `geometry: true` in a batch or inside a `map` throws when the callback runs.

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+import { type Decoded, type Recorder, type Shape } from './compose.js';
+import type { MatchResult, ProjectRequest, ProjectResult, ResolveRequest, SearchMatch, SearchRequest, SearchTarget } from './types.js';
+export type Token = string | (() => string | Promise<string>);
+export interface BifrostOptions {
+    baseUrl: string;
+    token?: Token;
+}
+export interface ValidationIssue {
+    loc: (string | number)[];
+    msg: string;
+    type: string;
+}
+export type ErrorDetail = string | ValidationIssue[];
+export declare class BifrostError extends Error {
+    readonly status: number;
+    readonly detail: ErrorDetail;
+    constructor(status: number, detail: ErrorDetail);
+}
+export declare class Bifrost {
+    #private;
+    constructor({ baseUrl, token }: BifrostOptions);
+    resolve(body: ResolveRequest): Promise<MatchResult>;
+    resolve(body: ResolveRequest[]): Promise<MatchResult[]>;
+    search<T extends SearchTarget>(body: SearchRequest<string, T>): Promise<MatchResult<SearchMatch<T>>>;
+    search<T extends SearchTarget>(body: SearchRequest<string, T>[]): Promise<MatchResult<SearchMatch<T>>[]>;
+    project(body: ProjectRequest): Promise<ProjectResult>;
+    project(body: ProjectRequest[]): Promise<ProjectResult[]>;
+    compose<S extends Shape>(fn: (q: Recorder) => S): Promise<Decoded<S>>;
+}

package/dist/client.js

@@ -0,0 +1,57 @@
+import { record } from './compose.js';
+export class BifrostError extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`${status}: ${typeof detail === 'string' ? detail : JSON.stringify(detail)}`);
+        this.name = 'BifrostError';
+        this.status = status;
+        this.detail = detail;
+    }
+}
+export class Bifrost {
+    #baseUrl;
+    #token;
+    constructor({ baseUrl, token }) {
+        this.#baseUrl = baseUrl.replace(/\/+$/, '');
+        this.#token = token;
+    }
+    resolve(body) {
+        return this.#post('/resolve', body);
+    }
+    search(body) {
+        return this.#post('/search', body);
+    }
+    project(body) {
+        return this.#post('/project', body);
+    }
+    async compose(fn) {
+        const { steps, decode } = record(fn);
+        const outputs = (await this.#post('/compose', { steps }));
+        return decode(outputs);
+    }
+    async #post(path, body) {
+        const headers = { 'content-type': 'application/json' };
+        const token = typeof this.#token === 'function' ? await this.#token() : this.#token;
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        const res = await fetch(this.#baseUrl + path, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body)
+        });
+        if (!res.ok)
+            throw new BifrostError(res.status, await detailOf(res));
+        return res.json();
+    }
+}
+async function detailOf(res) {
+    const text = await res.text();
+    try {
+        const { detail } = JSON.parse(text);
+        return detail ?? text;
+    }
+    catch {
+        return text;
+    }
+}

package/dist/compose.d.ts

@@ -0,0 +1,73 @@
+import type { MatchResult, ProjectRequest, ProjectResult, ProjectRoot, Ref, ResolveRequest, SearchMatch, SearchRequest, SearchTarget } from './types.js';
+declare const value: unique symbol;
+declare const step: unique symbol;
+declare const kind: unique symbol;
+export type Handle<T, U = never> = {
+    readonly [value]: T | U;
+} & Navigate<T, U | Gap<T>>;
+export type Step<T> = Handle<T> & {
+    readonly [step]: T;
+};
+export type Mapped<T> = {
+    readonly [value]: T[];
+};
+export type Shape = {
+    readonly [value]: unknown;
+} | {
+    readonly [key: string]: Shape;
+};
+export type Decoded<S> = S extends {
+    readonly [value]: infer T;
+} ? T : {
+    [K in keyof S]: Decoded<S[K]>;
+};
+export type Slot = string | Handle<string | null, undefined>;
+export type CodeSlot = string | Handle<string | number | null, undefined>;
+export type RefHandle = {
+    readonly [value]: string | undefined;
+    readonly [kind]: ProjectRoot;
+};
+export interface ProjectBody extends Omit<ProjectRequest<Slot>, 'input'> {
+    input: Ref<CodeSlot> | RefHandle | Handle<Ref | null, undefined>;
+}
+type Gap<T> = [Extract<T, null | undefined>] extends [never] ? never : undefined;
+type Optional<T, K extends keyof T> = {} extends Pick<T, K> ? undefined : never;
+type Navigate<T, U> = NonNullable<T> extends readonly (infer E)[] ? Items<E, U> : NonNullable<T> extends object ? Fields<NonNullable<T>, U> : unknown;
+type Fields<T, U> = {
+    readonly [K in keyof T]-?: K extends 'refs' ? Kinds<Required<T>[K], U | Optional<T, K>> : Handle<Required<T>[K], U | Optional<T, K>>;
+};
+type Kinds<R, U> = R extends readonly unknown[] ? Handle<R, U> : Handle<R, U> & {
+    readonly [K in keyof R]-?: {
+        readonly [kind]: K;
+    };
+};
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type Index = Digit | `${Exclude<Digit, '0'>}${Digit}` | `${Exclude<Digit, '0'>}${Digit}${Digit}`;
+type Items<E, U> = {
+    readonly [I in Index]: Handle<E, U | undefined>;
+} & {
+    readonly [n: number]: Handle<E, U | undefined>;
+    map<R extends Shape>(fn: (element: Handle<E>) => R): R extends {
+        readonly [step]: infer T;
+    } ? Step<T[]> : Mapped<Decoded<R>>;
+};
+export interface Recorder {
+    resolve(body: ResolveRequest<Slot>): Step<MatchResult>;
+    resolve(body: ResolveRequest<Slot>[]): Step<MatchResult[]>;
+    search<T extends SearchTarget>(body: SearchRequest<CodeSlot, T>): Step<MatchResult<SearchMatch<T>>>;
+    search<T extends SearchTarget>(body: SearchRequest<CodeSlot, T>[]): Step<MatchResult<SearchMatch<T>>[]>;
+    project(body: ProjectBody): Step<ProjectResult<Ref | null>>;
+    project(body: ProjectBody[]): Step<ProjectResult<Ref | null>[]>;
+}
+type Op = 'resolve' | 'search' | 'project';
+interface WireStep {
+    id: string;
+    op: Op;
+    body: unknown;
+    each?: string;
+}
+export declare function record(fn: (q: Recorder) => Shape): {
+    steps: WireStep[];
+    decode: (outputs: Record<string, unknown>) => unknown;
+};
+export {};

package/dist/compose.js

@@ -0,0 +1,110 @@
+const isRecord = (v) => typeof v === 'object' && v !== null && Object.getPrototypeOf(v) === Object.prototype;
+// mirrors the server's walk; a missing value reads undefined
+const walk = (v, path) => path.reduce((v, seg) => typeof seg === 'number'
+    ? Array.isArray(v) ? v[seg] : undefined
+    : isRecord(v) && Object.hasOwn(v, seg) ? v[seg] : undefined, v);
+const text = ({ root, path }) => root + path.map((seg) => (typeof seg === 'number' ? `[${seg}]` : `.${seg}`)).join('');
+export function record(fn) {
+    const steps = [];
+    const nodes = new Map();
+    const maps = new Map();
+    let mapping;
+    const live = (node, scope = mapping) => {
+        if (node.scope && node.scope !== scope)
+            throw new Error('handle used outside its map callback');
+    };
+    const handle = (node) => {
+        const proxy = new Proxy({}, {
+            get(_, key) {
+                // then must read undefined, or an accidental await never settles
+                if (typeof key === 'symbol' || key === 'then')
+                    return undefined;
+                if (key === 'toJSON')
+                    return () => ({ from: wire(node) });
+                if (key === 'map')
+                    return (fn) => map(node, fn);
+                const seg = /^\d+$/.test(key) ? Number(key) : key;
+                return handle({ ...node, path: [...node.path, seg] });
+            }
+        });
+        nodes.set(proxy, node);
+        return proxy;
+    };
+    const wire = (node) => {
+        live(node);
+        // an each step sees only its own element, never a sibling step's output for it
+        if (node.scope && node.root !== '@')
+            throw new Error('a step made in map can only be returned');
+        return text(node);
+    };
+    // one decoder per shape, built at record time so a bad shape throws before any request
+    const compile = (shape, scope) => {
+        const node = nodes.get(shape);
+        if (node) {
+            live(node, scope);
+            return (read) => walk(read(node.root), node.path);
+        }
+        const mapped = maps.get(shape);
+        if (mapped)
+            return mapped;
+        if (!isRecord(shape))
+            throw new Error('compose returns handles, maps and records of them');
+        const fields = Object.entries(shape).map(([key, v]) => [key, compile(v, scope)]);
+        return (read) => Object.fromEntries(fields.map(([key, f]) => [key, f(read)]));
+    };
+    const map = (source, fn) => {
+        live(source);
+        if (mapping)
+            throw new Error('map cannot nest');
+        const first = steps.length;
+        const element = {};
+        mapping = element;
+        let returned;
+        try {
+            returned = fn(handle({ root: '@', path: [], scope: element }));
+        }
+        finally {
+            mapping = undefined;
+        }
+        const made = steps.slice(first);
+        for (const s of made)
+            s.each = text(source);
+        const inner = new Set(made.map((s) => s.id));
+        const own = nodes.get(returned);
+        // typed as a step to chain from, but no each step runs it
+        if (own?.path.length === 0 && own.root !== '@') {
+            if (!inner.has(own.root))
+                throw new Error('map returns a step made outside its callback');
+            return handle({ root: own.root, path: [], scope: undefined });
+        }
+        const body = compile(returned, element);
+        const token = {};
+        maps.set(token, (read) => {
+            const items = walk(read(source.root), source.path);
+            if (!Array.isArray(items))
+                return [];
+            return items.map((el, i) => body((root) => (root === '@' ? el : inner.has(root) ? walk(read(root), [i]) : read(root))));
+        });
+        return token;
+    };
+    const call = (op) => (body) => {
+        // the server runs an each step as a batch, so both refuse geometry with one message
+        if ((mapping || Array.isArray(body)) && [body].flat().some((item) => item.geometry))
+            throw new Error('set geometry=false for every batch item');
+        const expand = (item) => {
+            const node = nodes.get(item.input);
+            const [parent, name] = node?.path.slice(-2) ?? [];
+            return parent === 'refs' && typeof name === 'string'
+                ? { ...item, input: { kind: name, id: item.input } }
+                : item;
+        };
+        const wired = op !== 'project' ? body : Array.isArray(body) ? body.map(expand) : expand(body);
+        const id = `s${steps.length}`;
+        // serialize now: a misused handle throws here, and later mutation cannot leak in
+        steps.push({ id, op, body: JSON.parse(JSON.stringify(wired)) });
+        return handle({ root: id, path: [], scope: mapping });
+    };
+    // the proxies are untyped; Recorder carries the types
+    const decode = compile(fn({ resolve: call('resolve'), search: call('search'), project: call('project') }), undefined);
+    return { steps, decode: (outputs) => decode((root) => outputs[root]) };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Bifrost, BifrostError } from './client.js';
+export type { BifrostOptions, ErrorDetail, Token, ValidationIssue } from './client.js';
+export type { CodeSlot, Decoded, Handle, Mapped, ProjectBody, Recorder, RefHandle, Shape, Slot, Step } from './compose.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { Bifrost, BifrostError } from './client.js';

package/dist/types.d.ts

@@ -0,0 +1,157 @@
+export type ProjectTarget = 'unit' | 'entrance' | 'street' | 'postcode' | 'city' | 'ejendom' | 'kommune' | 'sogn' | 'region' | 'retskreds' | 'politikreds' | 'opstillingskreds' | 'ejerlav';
+export type ProjectRoot = ProjectTarget;
+export type SearchTarget = Exclude<ProjectTarget, 'unit' | 'entrance'> | 'stednavn';
+export type FeatureKind = ProjectTarget | 'stednavn';
+export type Lifecycle = 'current' | 'preliminary' | 'retired' | 'abandoned';
+export type Confidence = 'A' | 'B' | 'C';
+export type EjendomType = 'samlet_fast_ejendom' | 'ejerlejlighed' | 'bygning_paa_fremmed_grund';
+export type ComponentField = 'street' | 'house_number' | 'house_letter' | 'floor' | 'door' | 'postcode' | 'city' | 'sub_locality';
+export type PinField = ComponentField | 'kommune' | 'sogn' | 'region';
+export type Pins<S = string> = {
+    [K in PinField]?: S;
+};
+export interface ResolveRequest<S = string> {
+    input?: S;
+    components?: Pins<S>;
+    lifecycle?: Lifecycle[];
+    limit?: number;
+    geometry?: boolean;
+}
+export interface SearchRequest<S = string, T extends SearchTarget = SearchTarget> {
+    input: S;
+    target: T;
+    limit?: number;
+    lifecycle?: Lifecycle[];
+    geometry?: boolean;
+}
+export interface Ref<S = string> {
+    kind: ProjectRoot;
+    id: S;
+}
+export interface ProjectRequest<S = string> {
+    input: Ref<S>;
+    target: ProjectTarget;
+    limit?: number;
+    cursor?: string;
+    lifecycle?: Lifecycle[];
+    geometry?: boolean;
+}
+export type Position = [number, number];
+export interface Point {
+    type: 'Point';
+    coordinates: Position;
+}
+export type GeoJsonGeometry = Point | {
+    type: 'MultiPoint';
+    coordinates: Position[];
+} | {
+    type: 'LineString';
+    coordinates: Position[];
+} | {
+    type: 'MultiLineString';
+    coordinates: Position[][];
+} | {
+    type: 'Polygon';
+    coordinates: Position[][];
+} | {
+    type: 'MultiPolygon';
+    coordinates: Position[][][];
+} | {
+    type: 'GeometryCollection';
+    geometries: GeoJsonGeometry[];
+};
+export interface Geometry {
+    srid: number;
+    geojson: GeoJsonGeometry;
+    vejpunkt: Position | null;
+}
+export interface Upstream {
+    source: string;
+    id: string | number;
+}
+export interface Meta {
+    score: number;
+    confidence: Confidence;
+    upstream: Partial<Record<FeatureKind, Upstream>>;
+}
+export interface PropertyRef {
+    id: string;
+    type: EjendomType;
+    ejerlejlighedsnummer?: string;
+    lifecycle: Lifecycle | null;
+    upstream: Upstream;
+}
+export interface PropertyRefs {
+    refs: PropertyRef[];
+    complete: boolean;
+}
+export interface Parcel {
+    matrikelnummer: string | null;
+    ejerlavskode: number | null;
+    ejerlav: string | null;
+    kommunekode: string | null;
+    kommune: string | null;
+    lifecycle: Lifecycle;
+    upstream: Upstream;
+}
+export interface Ejendom {
+    type: EjendomType;
+    ejerlejlighedsnummer?: string;
+    relations: {
+        parents: PropertyRefs;
+        children: PropertyRefs;
+    };
+    parcels: {
+        items: Parcel[];
+        complete: boolean;
+    };
+}
+type Area<Code extends string, Name extends string> = Record<Code, string> & Record<Name, string | null>;
+export interface Components {
+    street?: string;
+    house_number?: string;
+    house_letter?: string;
+    floor?: string;
+    door?: string;
+    sub_locality?: string;
+    stednavn?: string;
+    type?: string;
+    matrikelnummer?: string;
+    ejerlavskode?: number;
+    ejerlav?: string;
+    postcodes?: Area<'postcode', 'city'>[];
+    kommuner?: Area<'kommunekode', 'kommune'>[];
+    sogne?: Area<'sognekode', 'sogn'>[];
+    regioner?: Area<'regionskode', 'region'>[];
+    retskredse?: Area<'retskredsnummer', 'retskreds'>[];
+    politikredse?: Area<'politikredsnummer', 'politikreds'>[];
+    opstillingskredse?: Area<'opstillingskredsnummer', 'opstillingskreds'>[];
+}
+export interface StednavnRef {
+    kind: 'stednavn';
+    id: string;
+}
+export interface Match<R extends Ref | StednavnRef = Ref> {
+    ref: R;
+    refs: Partial<Record<FeatureKind, string>>;
+    result: string;
+    lifecycle: Lifecycle | null;
+    components: Components;
+    ejendom?: Ejendom;
+    point: Point | null;
+    geometry: Geometry | null;
+    meta: Meta;
+}
+export interface MatchResult<M extends Match<Ref | StednavnRef> = Match> {
+    input: string | null;
+    matches: M[];
+    error?: string;
+}
+export type SearchMatch<T extends SearchTarget> = T extends 'stednavn' ? Match<StednavnRef> : Match;
+export interface ProjectResult<I extends Ref | null = Ref> {
+    input: I;
+    matches: Match[];
+    next?: string;
+    error?: string;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+// wire types, mirroring app/src/bifrost/api/contract.py
+export {};

package/package.json

@@ -1,6 +1,30 @@
 {
-  "name": "@kalyptos/bifrost",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@kalyptos/bifrost",
+	"version": "5.0.0",
+	"description": "TypeScript client for the Bifrost Danish address API",
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kalyptos-io/bifrost.git",
+		"directory": "sdk"
+	},
+	"type": "module",
+	"exports": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"check": "tsc --noEmit",
+		"test": "vitest run",
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build"
+	},
+	"devDependencies": {
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.11"
+	}
+}