@geonosis/integrations 1.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 [yyyy] [name of copyright owner]
+
+   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

@@ -0,0 +1,211 @@
+# `@geonosis/integrations`
+
+One integration seam: a prefixed id, an optional settings schema, and a registry that refuses a
+duplicate id, an id outside its prefix, or a missing required id — at build time, once, instead of
+on every lookup for the life of the process.
+
+Zero runtime dependencies. It never imports zod.
+
+```bash
+pnpm add @geonosis/integrations
+```
+
+## Why
+
+dielime arrived at the same seam three times, with no shared code between them:
+`AbstractCrmProvider` + `buildCrmProviderRegistry` (`cp_*`), `AbstractSearchProvider` +
+`buildSearchProviderRegistry` (`sp_*`), and `AbstractMessagingChannelProvider` +
+`buildMessagingProviderRegistry` (`mp_*`). Midday is the same story one stage later: **five**
+incompatible plugin seams for one concept, a `UnifiedApp` manifest with 25 optional fields and
+`value: any`, a settings UI hand-mapped inside a dashboard component, and 8 of 35 integration
+directories reachable from nothing.
+
+The measured gain is smaller and sharper than "one shape for all of them". dielime declares
+
+```ts
+export const CRM_PROVIDER_PREFIX = 'cp_'      // modules/crm/types.ts:145
+export const SEARCH_PROVIDER_PREFIX = 'sp_'   // modules/search/types.ts:135
+```
+
+and **references neither anywhere else in the repo**. Both registries are a
+`Record<string, Provider>` built from an object literal, so:
+
+- a key that ignores the prefix is accepted;
+- a second entry under an id already taken silently replaces the first, and the one that disappears
+  is whichever was written higher up;
+- "the configured default must be registered" is checked inside `getActiveProvider()` — on every
+  call, forever — instead of once, when the registry is built.
+
+Two dead constants and three invariants stated in comments and held by nothing. This package holds
+them.
+
+## API
+
+### `defineIntegration({ id, settingsSchema?, health?, isConfigured? })`
+
+```ts
+import { defineIntegration } from '@geonosis/integrations'
+import { z } from 'zod'
+
+export const attio = defineIntegration({
+  id: 'cp_attio',
+  settingsSchema: z.object({
+    apiKey: z.string().describe('The Attio API key'),
+    baseUrl: z.string().optional(),
+  }),
+  health: () => client.ping(),
+  isConfigured: () => apiKey !== undefined,
+})
+```
+
+Refuses an empty or non-string `id`, a `settingsSchema` with no `safeParse`, and a `health` or
+`isConfigured` that is not callable.
+
+`health` and `isConfigured` are the two probes `AbstractCrmProvider` and `AbstractSearchProvider`
+both declare. Everything a provider does beyond them — `upsertContact`, `search`, `parseInbound` —
+is the consumer's own contract and stays there; this package holds the seam, not the work.
+
+### `createIntegrationRegistry({ prefix, integrations, requiredId? })`
+
+```ts
+const crm = createIntegrationRegistry({
+  prefix: 'cp_',
+  integrations: [attio, hubspot],
+  requiredId: 'cp_attio',
+})
+
+crm.get('cp_attio')   // throws, naming what IS registered, if absent
+crm.has('cp_hubspot') // boolean, no throw
+crm.list()            // declaration order
+crm.required()        // the `requiredId` integration
+crm.prefix            // 'cp_'
+```
+
+Refuses, when built: an empty `prefix`; an entry that never went through `defineIntegration`; an id
+outside the prefix; a duplicate id; a `requiredId` outside the prefix or absent from the list.
+
+`requiredId` is dielime's `DEFAULT_CRM_PROVIDER_ID` / `DEFAULT_SEARCH_PROVIDER_ID` plus the
+`NOT_FOUND` its `getActiveProvider()` throws — moved to the one moment the question can be answered
+once. (Plan 022 called this option `manualImplementationRequired`; it is named for the consumer
+construct it extracts.)
+
+### `settingsFieldsOf(integration)`
+
+A JSON description of the settings schema's fields, so a settings form is **derived** rather than
+hand-mapped:
+
+```ts
+settingsFieldsOf(attio)
+// [ { name: 'apiKey', type: 'string', required: true, description: 'The Attio API key' },
+//   { name: 'baseUrl', type: 'string', required: false } ]
+```
+
+`optional`, `default` and `prefault` make a field not required; `nullable` and `readonly` are peeled
+without changing that; an enum carries its choices as `options`. An integration with no schema, or
+a schema that is not an object of fields, has no fields. A schema this reader **cannot see into**
+throws rather than returning an empty list — a blank settings page with no explanation is the silent
+zero this kit refuses everywhere else.
+
+## The one shape this package does not replace
+
+dielime's third seam is not this shape and is deliberately out of scope:
+
+```ts
+buildMessagingProviderRegistry(): Record<CommunicationChannel, AbstractMessagingChannelProvider | undefined>
+```
+
+It is keyed by `CommunicationChannel`, not by a prefixed id — the `mp_*` ids live in a separate
+`MESSAGING_PROVIDER_IDS` map the registry never uses — and it is **total with holes**: `sms`,
+`telegram` and `webchat` are present and `undefined`, so a new channel breaks the build until
+someone answers for it. Its own test asserts exactly that:
+
+```ts
+expect(reg.sms).toBeUndefined()   // providers.test.ts:157
+```
+
+A registry that refuses a non-integration destroys the totality that test protects. That is a
+second registry shape — keyed and total over a declared union — and replacing it with this one would
+be a downgrade. It is the only registry test either consumer has, which is why it is quoted here
+rather than summarised.
+
+## Migration — dielime, five lines
+
+```diff
+-export function buildCrmProviderRegistry(opts: CrmProviderOptions = {}): Record<string, AbstractCrmProvider> {
+-  return { [DEFAULT_CRM_PROVIDER_ID]: new AttioCrmProviderService(...), [CRM_PROVIDER_IDS.hubspot]: new HubspotCrmProviderService(...) }
+-}
++export const buildCrmProviderRegistry = (opts: CrmProviderOptions = {}) =>
++  createIntegrationRegistry({
++    prefix: CRM_PROVIDER_PREFIX,
++    requiredId: DEFAULT_CRM_PROVIDER_ID,
++    integrations: [attioIntegration(opts), hubspotIntegration(opts)],
++  })
+```
+
+`getActiveProvider()` becomes `registry.required()`, and its `NOT_FOUND` throw is deleted — the
+registry already refused to exist. `CRM_PROVIDER_PREFIX` stops being a dead export.
+
+## Migration — during.day, five lines
+
+`apps/web/features/apps/stores/apps-store.ts` is a hardcoded array of 12 `AppDefinition`s
+(`{ category, description, icon, id, name }`) with client-only `installedIds` and no server half.
+Its first real integration is where the seam is worth having:
+
+```diff
+-const DEFAULT_APPS: AppDefinition[] = [ { id: 'slack', name: 'Slack', ... }, ... ]
++export const apps = createIntegrationRegistry({
++  prefix: 'app_',
++  integrations: [slack, gmail, outlook],
++})
+```
+
+The presentation fields (`category`, `description`, `icon`, `name`) stay in during.day: they are a
+UI catalogue, and this package deliberately carries no manifest. See below.
+
+## Equivalence status (D-027)
+
+| Piece | Status |
+|---|---|
+| `createIntegrationRegistry` — prefix, duplicates, `requiredId` | **extracted** — three consumer copies, the invariants they state and do not hold |
+| `defineIntegration` — `id`, `health`, `isConfigured` | **extracted** — the fields two of the three abstractions declare |
+| `settingsSchema` + `settingsFieldsOf` | **from Midday's failure, no consumer fixture yet** — neither consumer holds a settings schema today; the field exists because `value: any` plus a hand-mapped dashboard component is where its absence leads |
+| manifest (`name`, `category`, `description`, `logo`) | **not here** — Midday's is 25 optional fields, and neither consumer's provider carries one |
+| install lifecycle (`installUrl`, `onCallback`, `onUninstall`) | **not here** — zero occurrences in either consumer. dielime's integrations are credential-configured; during.day's have no server half. It waits for a consumer that holds one |
+| the channel-keyed registry | **not replaced** — see above |
+
+**Adopted by:** nobody yet. This is a published package with contract tests over both consumers'
+measured shapes, not a migration that has happened.
+
+## zod, and why the guard is structural
+
+`settingsSchema` is typed structurally — `{ safeParse }` — and checked the same way. This package
+never imports zod, and has no runtime dependencies at all. The declared peer is `^4.0.0`, optional.
+
+The reason, measured rather than assumed:
+
+| | dielime plugins | dielime root | during.day |
+|---|---|---|---|
+| import specifier | `@medusajs/framework/zod` | `zod` | `zod` (catalog) |
+| resolved version | **4.2.0** (via `@medusajs/deps`) | 4.4.3 | 4.5.4 |
+
+Three module instances of one major, across two consumers, with genuinely different constructors
+and prototypes.
+
+The obvious conclusion from that — "so an `instanceof z.ZodType` guard would refuse dielime's
+schemas" — **is wrong for zod 4, and this package's tests are where that was found out.** Zod 4 puts
+a `Symbol.hasInstance` on its classes that answers by an internal trait rather than by the prototype
+chain, so `instanceof` bridges copies of zod 4 fine. It does **not** bridge zod 3, whose schemas are
+plain classes — and dielime's own root package declares its zod peer as `^3.0.0 || ^4.0.0`.
+
+So the structural guard is still the right one, for the reasons that survived the measurement: it
+asks what a schema does, which every copy and every major answers identically; and it needs no
+import, which keeps this package out of the version disagreement entirely. `settingsFieldsOf` reads
+zod 4 internals and says so loudly when handed something else.
+
+`src/realms.test.ts` asserts all of it against three real copies of zod (4.5, 4.2 and 3.25) in one
+process, starting with the assertion that they are genuinely different modules — without which the
+rest would pass and prove nothing.
+
+## Licence
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * One integration seam, carrying what the consumers actually hold.
+ *
+ * dielime arrived at the same shape three times — `AbstractCrmProvider` (`cp_*`),
+ * `AbstractSearchProvider` (`sp_*`) and `AbstractMessagingChannelProvider` (`mp_*`), each with its
+ * own registry builder and no shared code. Two of the three declare `health()` and `isConfigured()`;
+ * all three key on an id. Those are the fields below that are extraction.
+ *
+ * `settingsSchema` is the one field taken from a failure rather than from a consumer. Midday's
+ * `UnifiedApp` carries a 25-optional-field manifest whose `settings` are data typed `value: any`,
+ * and the UI that renders them is a hardcoded map inside a dashboard component, with a config type
+ * that covers 6 of its 27 apps. A schema instead of an array is what lets the form be derived —
+ * see `settingsFieldsOf` — so the validator and the UI cannot disagree.
+ *
+ * There is deliberately no install lifecycle here. `installUrl`, `onCallback` and `onUninstall`
+ * appear nowhere in either consumer: dielime's integrations are credential-configured, and
+ * during.day's are a hardcoded array in a Zustand store with no server half at all. They wait for
+ * a consumer that holds one.
+ */
+/**
+ * A schema, recognised by what it does rather than by what it is an instance of.
+ *
+ * This is not squeamishness about types. dielime imports `z` from `@medusajs/framework/zod` under a
+ * repo rule forbidding bare `zod`, and that resolves to the copy `@medusajs/deps` ships (4.2.0),
+ * while its own root devDependency is 4.4.3 and during.day's catalog is 4.5.4 — three module
+ * instances of one major, across two consumers. `value instanceof z.ZodType` compares against a
+ * class object, and a schema from another copy of zod is not an instance of ours. Such a guard
+ * passes every test written against the kit's own zod and refuses every schema dielime hands it.
+ */
+type SchemaLike = {
+    safeParse: (value: unknown) => unknown;
+};
+type Integration<Id extends string = string> = {
+    health?: () => Promise<boolean>;
+    id: Id;
+    isConfigured?: () => boolean;
+    settingsSchema?: SchemaLike;
+};
+type IntegrationInput<Id extends string = string> = Integration<Id>;
+/** Whether this object went through `defineIntegration` rather than being written out by hand. */
+declare const isIntegration: (value: unknown) => value is Integration;
+declare const defineIntegration: <const Id extends string>(input: IntegrationInput<Id>) => Integration<Id>;
+
+/**
+ * The registry both prefixed-id seams already have, with the invariants they state and do not hold.
+ *
+ * dielime declares `CRM_PROVIDER_PREFIX = 'cp_'` in `modules/crm/types.ts` and
+ * `SEARCH_PROVIDER_PREFIX = 'sp_'` in `modules/search/types.ts`, and references neither anywhere
+ * else in the repo — two exports that exist to document a convention nothing enforces. Both
+ * registries are a `Record<string, Provider>` built from an object literal, so a key that ignores
+ * the prefix is accepted, a second entry under an id already taken silently replaces the first, and
+ * "the configured default must be registered" is checked inside `getActiveProvider()` on every
+ * call, for the life of the process, instead of once when the registry is built.
+ *
+ * Those three are what this holds. It is not a different design; it is the design the comments
+ * already describe, made refusable.
+ *
+ * It covers ONE of the three seams' shapes: lookup by prefixed id. The messaging registry is keyed
+ * by `CommunicationChannel` and holds `undefined` for the channels it has not built — a totality
+ * over a declared union, which its own test asserts. That is a second shape, and this package does
+ * not replace it.
+ */
+type RegistryInput<Id extends string = string> = {
+    integrations: readonly Integration<Id>[];
+    prefix: string;
+    /**
+     * The id that must be present for the registry to be worth building — dielime spells it
+     * `DEFAULT_CRM_PROVIDER_ID` / `DEFAULT_SEARCH_PROVIDER_ID`, and its absence is a `NOT_FOUND`
+     * thrown on first use rather than a refusal to start.
+     */
+    requiredId?: Id;
+};
+type IntegrationRegistry<Id extends string = string> = {
+    get: (id: string) => Integration<Id>;
+    has: (id: string) => boolean;
+    list: () => readonly Integration<Id>[];
+    prefix: string;
+    required: () => Integration<Id>;
+};
+declare const createIntegrationRegistry: <const Id extends string>(input: RegistryInput<Id>) => IntegrationRegistry<Id>;
+
+/**
+ * The settings form, read off the schema that already validates the settings.
+ *
+ * Midday routes an app's OAuth start through a hardcoded endpoint map inside a dashboard component,
+ * hand-writes a React component per MCP client for its setup instructions, and types its stored
+ * config with a conditional map covering 6 of 27 apps. Every one of those is the same act: a fact
+ * about an integration, restated somewhere the integration cannot see. Deriving the fields is how
+ * the restatement stops being possible.
+ *
+ * This returns a description, not a UI. What a `string` field looks like is the consumer's
+ * business; that there IS a required string called `apiKey` is the schema's.
+ */
+type SettingsField = {
+    description?: string;
+    name: string;
+    options?: readonly string[];
+    required: boolean;
+    type: string;
+};
+/**
+ * The fields, or none — but never none because the schema could not be read.
+ *
+ * An integration with no settings schema, and one whose schema is a `string` rather than an object
+ * of fields, both have nothing to render, and an empty list is the honest answer for both. A schema
+ * this reader cannot see INTO is a different thing entirely: zod 3 keeps its shape behind `_def`
+ * and spells it as a function, so a zod 3 object would come back with no fields and render a
+ * settings page that is blank for a reason nothing on it explains. That is the silent zero a
+ * counter reports under a format it cannot parse, wearing a form's clothes, so it is refused.
+ */
+declare const settingsFieldsOf: (integration: Integration) => SettingsField[];
+
+export { type Integration, type IntegrationInput, type IntegrationRegistry, type RegistryInput, type SchemaLike, type SettingsField, createIntegrationRegistry, defineIntegration, isIntegration, settingsFieldsOf };

package/dist/index.js

@@ -0,0 +1,142 @@
+// src/define.ts
+var DECLARED = /* @__PURE__ */ Symbol.for("geonosis.integrations.declared");
+var isIntegration = (value) => typeof value === "object" && value !== null && value[DECLARED] === true;
+var requireCallable = (value, field, id) => {
+  if (value !== void 0 && typeof value !== "function") {
+    throw new TypeError(
+      `defineIntegration("${id}"): \`${field}\` must be a function, and is ${typeof value}. A probe that cannot be called is a probe nobody runs.`
+    );
+  }
+};
+var defineIntegration = (input) => {
+  const { health, id, isConfigured, settingsSchema } = input;
+  if (typeof id !== "string" || id === "") {
+    throw new TypeError(
+      "defineIntegration: `id` must be a non-empty string. An integration with no id cannot be registered, looked up, or named in a diagnostic."
+    );
+  }
+  if (settingsSchema !== void 0 && typeof settingsSchema.safeParse !== "function") {
+    throw new TypeError(
+      `defineIntegration("${id}"): \`settingsSchema\` must expose \`safeParse\`. A settings description that cannot validate anything is Midday's \`value: any\` with a schema-shaped name on it \u2014 the settings UI is generated from this, so nothing else can stand in for it.`
+    );
+  }
+  requireCallable(health, "health", id);
+  requireCallable(isConfigured, "isConfigured", id);
+  return { ...input, [DECLARED]: true };
+};
+
+// src/registry.ts
+var prefixed = (id, prefix) => id.startsWith(prefix);
+var createIntegrationRegistry = (input) => {
+  const { integrations, prefix, requiredId } = input;
+  if (typeof prefix !== "string" || prefix === "") {
+    throw new TypeError(
+      "createIntegrationRegistry: `prefix` must be a non-empty string. A prefix that is nothing enforces nothing, and a check that cannot fail reads exactly like a check that found nothing \u2014 which is how both consumers ended up with a prefix constant referenced by no code."
+    );
+  }
+  const byId = /* @__PURE__ */ new Map();
+  for (const integration of integrations ?? []) {
+    if (!isIntegration(integration)) {
+      throw new TypeError(
+        `createIntegrationRegistry("${prefix}"): every entry must come from \`defineIntegration\`. An object literal skips the checks on the id, the settings schema and the probes, which is the hand-written manifest this package exists to replace.`
+      );
+    }
+    if (!prefixed(integration.id, prefix)) {
+      throw new Error(
+        `createIntegrationRegistry("${prefix}"): "${integration.id}" does not carry the prefix "${prefix}". The prefix is the registry's namespace; an id outside it collides with whatever else shares the container.`
+      );
+    }
+    if (byId.has(integration.id)) {
+      throw new Error(
+        `createIntegrationRegistry("${prefix}"): "${integration.id}" is registered twice. In an object literal the second entry silently replaces the first, and the integration that disappears is whichever was written higher up.`
+      );
+    }
+    byId.set(integration.id, integration);
+  }
+  if (requiredId !== void 0) {
+    if (!prefixed(requiredId, prefix)) {
+      throw new Error(
+        `createIntegrationRegistry("${prefix}"): the required id "${requiredId}" does not carry the prefix "${prefix}".`
+      );
+    }
+    if (!byId.has(requiredId)) {
+      throw new Error(
+        `createIntegrationRegistry("${prefix}"): the required id "${requiredId}" is not registered. It is the one integration this registry is not worth building without, so it is refused here rather than on the first lookup that happens to want it.`
+      );
+    }
+  }
+  const get = (id) => {
+    const found = byId.get(id);
+    if (found === void 0) {
+      throw new Error(
+        `Integration "${id}" is not registered. Registered under "${prefix}": ${[...byId.keys()].join(", ") || "nothing"}.`
+      );
+    }
+    return found;
+  };
+  return {
+    get,
+    has: (id) => byId.has(id),
+    list: () => [...byId.values()],
+    prefix,
+    required: () => {
+      if (requiredId === void 0) {
+        throw new Error(
+          `createIntegrationRegistry("${prefix}") named no \`requiredId\`, so there is no required integration to hand back. Name one, or ask for an id.`
+        );
+      }
+      return get(requiredId);
+    }
+  };
+};
+
+// src/settings.ts
+var OPTIONAL_WRAPPERS = /* @__PURE__ */ new Set(["default", "optional", "prefault"]);
+var WRAPPERS = /* @__PURE__ */ new Set([...OPTIONAL_WRAPPERS, "nullable", "readonly"]);
+var asZod = (schema) => schema === void 0 ? void 0 : schema;
+var unwrap = (field) => {
+  let schema = field;
+  let required = true;
+  let description = field.description;
+  for (let depth = 0; depth < 10; depth += 1) {
+    const type = schema.def?.type;
+    const inner = schema.def?.innerType;
+    if (type === void 0 || inner === void 0 || !WRAPPERS.has(type)) break;
+    if (OPTIONAL_WRAPPERS.has(type)) required = false;
+    schema = inner;
+    description = description ?? schema.description;
+  }
+  return { description, required, schema };
+};
+var optionsOf = (schema) => {
+  const entries = schema.def?.entries;
+  if (entries === void 0) return void 0;
+  return Object.values(entries).map(String);
+};
+var settingsFieldsOf = (integration) => {
+  const schema = asZod(integration.settingsSchema);
+  if (schema === void 0) return [];
+  if (schema.def === void 0) {
+    throw new TypeError(
+      `settingsFieldsOf("${integration.id}"): the settings schema is not one this reader can see into. It parses, so it is a schema \u2014 but its fields are not where zod 4 keeps them, and zod 3 spells its shape as a function behind \`_def\`. Pass a zod 4 schema (the declared peer is ^4.0.0), or build the fields by hand for this one.`
+    );
+  }
+  const shape = schema.def.shape;
+  if (shape === void 0) return [];
+  return Object.entries(shape).map(([name, field]) => {
+    const { description, required, schema: inner } = unwrap(field);
+    return {
+      description,
+      name,
+      options: optionsOf(inner),
+      required,
+      type: inner.def?.type ?? "unknown"
+    };
+  });
+};
+export {
+  createIntegrationRegistry,
+  defineIntegration,
+  isIntegration,
+  settingsFieldsOf
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@geonosis/integrations",
+  "version": "1.0.0",
+  "description": "One integration seam: a prefixed id, an optional settings schema, one registry that refuses a duplicate, a wrong prefix or a missing required id — and settings fields derived from the schema rather than hand-mapped.",
+  "keywords": [
+    "integrations",
+    "plugin",
+    "registry",
+    "provider",
+    "zod",
+    "settings"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/packages/integrations",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "packages/integrations"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "zod": "^4.0.0",
+    "zod-4-2": "npm:zod@4.2.0",
+    "zod-3": "npm:zod@3.25.76"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}