@roostorg/types 1.1.0 → 2.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@roostorg/types",
   "type": "module",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Shared types across Coop services",
   "module": "transpiled/index.js",
   "typings": "./transpiled/index.d.ts",
@@ -10,6 +10,11 @@
     "prepublishOnly": "npm run build",
     "test": "npm run build && node --test transpiled/test_scripts/"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/roostorg/coop",
+    "directory": "types"
+  },
   "author": "Roostorg",
   "files": [
     "transpiled"

package/transpiled/index.d.ts

@@ -190,5 +190,5 @@ export declare const ItemTypeKind: {
     USER: "USER";
 };
 export type ItemTypeKind = keyof typeof ItemTypeKind;
-export type { CoopIntegrationConfigEntry, CoopIntegrationPlugin, CoopIntegrationsConfig, IntegrationCredentialField, IntegrationId, IntegrationManifest, ModelCard, ModelCardField, ModelCardSection, ModelCardSubsection, StoredIntegrationConfigPayload, } from './integration.js';
+export type { CoopIntegrationConfigEntry, CoopIntegrationPlugin, CoopIntegrationsConfig, IntegrationConfigField, IntegrationId, IntegrationManifest, ModelCard, ModelCardField, ModelCardSection, ModelCardSubsection, PluginSignalContext, PluginSignalDescriptor, StoredIntegrationConfigPayload, } from './integration.js';
 export { assertModelCardHasRequiredSections, isCoopIntegrationPlugin, REQUIRED_MODEL_CARD_SECTION_IDS, } from './integration.js';

package/transpiled/integration.d.ts

@@ -31,7 +31,7 @@ export type ModelCardSubsection = Readonly<{
  * Either subsections (with bold sub-headings) or top-level fields, or both.
  */
 export type ModelCardSection = Readonly<{
-    /** Stable id for the section (e.g. "modelDetails", "trainingData"). */
+    /** Stable id for the section (e.g. "trainingData", "biasAndLimitations"). */
     id: string;
     /** Display title (e.g. "Model Details"). */
     title: string;
@@ -62,19 +62,19 @@ export type ModelCard = Readonly<{
  * Section ids that every integration's model card must include.
  * Use assertModelCardHasRequiredSections() to validate at runtime.
  */
-export declare const REQUIRED_MODEL_CARD_SECTION_IDS: readonly ["modelDetails", "technicalIntegration"];
+export declare const REQUIRED_MODEL_CARD_SECTION_IDS: readonly ["trainingData", "policyAndTaxonomy", "annotationMethodology", "performanceBenchmarks", "biasAndLimitations", "implementationGuidance", "relevantLinks"];
 /**
- * Asserts that a model card has at least the required sections (basic information
- * and technical integration). Call when registering integration manifests.
+ * Asserts that a model card has at least the required sections.
+ * Call when registering integration manifests.
  * @throws Error if any required section id is missing
  */
 export declare function assertModelCardHasRequiredSections(card: ModelCard): void;
 /**
- * Describes a single credential field for integrations that require
- * API keys or other secrets. Used to generate or validate credential forms.
+ * Describes a single configuration field for integrations that require
+ * user-supplied config (e.g. API keys or other settings). Used to generate or validate config forms.
  */
-export type IntegrationCredentialField = Readonly<{
-    /** Form field key (e.g. "apiKey", "labelerVersions"). */
+export type IntegrationConfigField = Readonly<{
+    /** Form field key (e.g. "apiKey", "truePercentage"). */
     key: string;
     /** Human-readable label for the field. */
     label: string;
@@ -94,7 +94,7 @@ export type IntegrationCredentialField = Readonly<{
 export type IntegrationManifest = Readonly<{
     /** Unique integration id. Must be UPPER_SNAKE_CASE to align with GraphQL enums when used in COOP. */
     id: IntegrationId;
-    /** Human-readable display name (e.g. "Google Content Safety API"). */
+    /** Human-readable display name shown in the UI (e.g. signal modal, integration cards). Exposed as Signal.integrationTitle. */
     name: string;
     /** Semantic version of the integration plugin (e.g. "1.0.0"). */
     version: string;
@@ -102,17 +102,13 @@ export type IntegrationManifest = Readonly<{
     description?: string;
     /** Link to documentation or product page. */
     docsUrl?: string;
-    /** Optional URL to a logo image (or asset key if using a bundler). */
-    logoUrl?: string;
-    /** Optional URL to a logo variant (e.g. with background) for cards. */
-    logoWithBackgroundUrl?: string;
-    /** Whether this integration requires the user to supply credentials (e.g. API key). */
-    requiresCredentials: boolean;
+    /** Whether this integration requires the user to supply config (e.g. API key). */
+    requiresConfig: boolean;
     /**
-     * Schema for credential fields when requiresCredentials is true.
+     * Schema for configuration fields when requiresConfig is true.
      * Enables UI generation and validation without hardcoding per-integration forms.
      */
-    credentialFields?: readonly IntegrationCredentialField[];
+    configurationFields?: readonly IntegrationConfigField[];
     /**
      * Optional list of signal type ids this integration provides (e.g. "ZENTROPI_LABELER").
      * Used by the platform to associate signals with this integration for display and gating.
@@ -120,12 +116,82 @@ export type IntegrationManifest = Readonly<{
     signalTypeIds?: readonly string[];
     /**
      * Model card: structured metadata (model name, version, sections) for the UI.
-     * When present, the integration detail page renders it. Built-in integrations
-     * should always provide a model card with at least sections "modelDetails" and
-     * "technicalIntegration"; use assertModelCardHasRequiredSections() when
-     * registering.
+     * When present, the integration detail page renders it. Integrations must
+     * include all sections listed in REQUIRED_MODEL_CARD_SECTION_IDS; use
+     * assertModelCardHasRequiredSections() when registering.
      */
     modelCard?: ModelCard;
+    /**
+     * ------------------------------------------------------------
+     * LOGO/IMAGE SECTION:
+     * ------------------------------------------------------------
+     * The following logo/image sections are optional. If none provided will use a fallback Coop logo.
+     *
+     * Provide either logoUrl and logoWithBackgroundUrl or logoPath and logoWithBackgroundPath.
+     *
+     * If you provide logoPath and logoWithBackgroundPath, the server will serve the files at
+     * GET /api/v1/integration-logos/:integrationId and GET /api/v1/integration-logos/:integrationId/with-background
+     * and set logoUrl and logoWithBackgroundUrl accordingly.
+     * Usage: logoUrl/logoPath = plain logo (no background), used on the integrations page;
+     * logoWithBackgroundUrl/logoWithBackgroundPath = logo with background, used in signal modals.
+     * If you provide logoUrl and logoWithBackgroundUrl, the server will use those URLs directly.
+     * Prefered size: ~180x180px for logoUrl and ~120x120px for logoWithBackgroundUrl.
+     * Prefer a square or horizontal logo that scales well.
+     */
+    logoUrl?: string;
+    logoWithBackgroundUrl?: string;
+    logoPath?: string;
+    logoWithBackgroundPath?: string;
+}>;
+/** Context passed to plugin.createSignals() so the plugin can build signal instances with credential access. */
+export type PluginSignalContext = Readonly<{
+    /** Integration id (e.g. "ACME_API") from the plugin manifest. */
+    integrationId: string;
+    /** Get stored credential/config for an org. Resolves to the JSON stored for this integration. */
+    getCredential: (orgId: string) => Promise<Record<string, unknown>>;
+}>;
+/** Minimal signal descriptor returned by a plugin. The platform adapts this to its internal SignalBase. */
+export type PluginSignalDescriptor = Readonly<{
+    /** Stable signal type id (e.g. "ACME_MODERATION_SIGNAL"). Must match one of manifest.signalTypeIds. */
+    id: Readonly<{
+        type: string;
+    }>;
+    displayName: string;
+    description: string;
+    docsUrl: string | null;
+    recommendedThresholds: Readonly<{
+        highPrecisionThreshold: string | number;
+        highRecallThreshold: string | number;
+    }> | null;
+    supportedLanguages: readonly string[] | 'ALL';
+    pricingStructure: Readonly<{
+        type: 'FREE' | 'SUBSCRIPTION';
+    }>;
+    eligibleInputs: readonly string[];
+    outputType: Readonly<{
+        scalarType: string;
+    }>;
+    getCost: () => number;
+    /** Run the signal. Input shape is platform-defined; result must have outputType and score. */
+    run: (input: unknown) => Promise<unknown>;
+    getDisabledInfo: (orgId: string) => Promise<{
+        disabled: false;
+        disabledMessage?: string;
+    } | {
+        disabled: true;
+        disabledMessage: string;
+    }>;
+    needsMatchingValues: boolean;
+    eligibleSubcategories: ReadonlyArray<{
+        id: string;
+        label: string;
+        description?: string;
+        childrenIds: readonly string[];
+    }>;
+    needsActionPenalties: boolean;
+    /** Integration id (same as context.integrationId). */
+    integration: string;
+    allowedInAutomatedRules: boolean;
 }>;
 /**
  * Plugin contract that third-party integration packages must implement.
@@ -136,6 +202,9 @@ export type IntegrationManifest = Readonly<{
  *   const manifest: IntegrationManifest = { id: 'ACME_API', name: 'Acme API', ... };
  *   const plugin: CoopIntegrationPlugin = { manifest };
  *   export default plugin;
+ *
+ * To power routing/enforcement rules, also implement createSignals(context) and
+ * return one descriptor per manifest.signalTypeIds entry.
  */
 export type CoopIntegrationPlugin = Readonly<{
     manifest: IntegrationManifest;
@@ -144,6 +213,15 @@ export type CoopIntegrationPlugin = Readonly<{
      * If present, adopters can pass non-secret config in the integrations config file.
      */
     configSchema?: unknown;
+    /**
+     * Optional. If this integration provides signals for use in rules, implement this.
+     * Return one descriptor per signal type id listed in manifest.signalTypeIds.
+     * The platform will register these so they appear in the rule builder and can be used in conditions.
+     */
+    createSignals?: (context: PluginSignalContext) => ReadonlyArray<Readonly<{
+        signalTypeId: string;
+        signal: PluginSignalDescriptor;
+    }>>;
 }>;
 /**
  * Single entry in the adopters' integrations config file.
@@ -177,7 +255,7 @@ export type CoopIntegrationsConfig = Readonly<{
  * Shape of the config stored in the database for each integration (per org).
  * Stored in a generic table as JSON: one row per (org_id, integration_id) with
  * config as a JSON-serializable object. Each integration defines its own required
- * fields via IntegrationManifest.credentialFields; the app validates and
+ * fields via IntegrationManifest.configurationFields; the app validates and
  * serializes/deserializes to this type.
  *
  * Only JSON-serializable values (no functions, symbols, or BigInt) should be

package/transpiled/integration.js

@@ -13,20 +13,24 @@
  * Use assertModelCardHasRequiredSections() to validate at runtime.
  */
 export const REQUIRED_MODEL_CARD_SECTION_IDS = [
-    'modelDetails',
-    'technicalIntegration',
+    'trainingData',
+    'policyAndTaxonomy',
+    'annotationMethodology',
+    'performanceBenchmarks',
+    'biasAndLimitations',
+    'implementationGuidance',
+    'relevantLinks',
 ];
 /**
- * Asserts that a model card has at least the required sections (basic information
- * and technical integration). Call when registering integration manifests.
+ * Asserts that a model card has at least the required sections.
+ * Call when registering integration manifests.
  * @throws Error if any required section id is missing
  */
 export function assertModelCardHasRequiredSections(card) {
     const sectionIds = new Set((card.sections ?? []).map((s) => s.id));
-    for (const requiredId of REQUIRED_MODEL_CARD_SECTION_IDS) {
-        if (!sectionIds.has(requiredId)) {
-            throw new Error(`Model card must include a section with id "${requiredId}" (e.g. Basic Information / Model Details and Technical Integration).`);
-        }
+    const missing = REQUIRED_MODEL_CARD_SECTION_IDS.filter((id) => !sectionIds.has(id));
+    if (missing.length > 0) {
+        throw new Error(`Model card is missing required section(s): ${missing.map((id) => `"${id}"`).join(', ')}.`);
     }
 }
 /**
@@ -44,5 +48,5 @@ export function isCoopIntegrationPlugin(value) {
     return (typeof m.id === 'string' &&
         typeof m.name === 'string' &&
         typeof m.version === 'string' &&
-        typeof m.requiresCredentials === 'boolean');
+        typeof m.requiresConfig === 'boolean');
 }