Entrypoints

​

Root: @ekanos/sdk

• IntegrationMetadata — host-resolved integration metadata (product id, slug, name, category)
• IntegrationContext — the ctx type
• StorageSchemas — schema map types
• Component prop types: IntegrationComponentProps, MarketplaceTileProps, ActivationFormProps
• Data types: HealthCheckResult, ActivationResult, IntegrationConfig

import type { IntegrationMetadata, IntegrationContext } from '@ekanos/sdk';

​

Components: @ekanos/sdk/components

• Widget — compound component API for dashboard widgets
• BaseActivationForm — form wrapper with dialog chrome
• OAuthActivationForm — OAuth variant
• BaseMarketplaceTile — generic marketplace card
• Context providers: WidgetContext, WidgetPreviewProvider
• Utilities: AiPromptChip, WidgetAskBar, currentReturnPath()

import { Widget, WidgetContext } from '@ekanos/sdk/components';
import { BaseActivationForm } from '@ekanos/sdk/components';

​

Hooks: @ekanos/sdk/hooks

• useActivateIntegration() — submit the activation form
• useDeactivateIntegration() — disconnect
• useOAuthConnectionStatus() — check OAuth state
• useIntegrationAction() — call widget actions
• useIntegrationFetch() / IntegrationFetchProvider — the fetch a widget’s queries should use (defaults to globalThis.fetch outside a provider; no client-side egress enforcement)
• useActivationData() / IntegrationActivationDataProvider — activation data in widgets (null outside a provider)
• fetchIntegrationStorage() — read clientReadable storage keys
• partnerOAuthConnectPath(), partnerOAuthStatusUrl() — OAuth flow helpers
• Event bus: useWidgetEventBus(), useWidgetEvents()

import {
  useActivateIntegration,
  fetchIntegrationStorage,
} from '@ekanos/sdk/hooks';

​

Context: @ekanos/sdk/context

• Error classes: EgressDeniedError, SecretAccessError, StorageValidationError
• Validators: assertStorageKeyDeclared(), parseStorageValue()
• Matchers: isEgressAllowed(), isStorageKeyClientReadable()
• Utilities: requireContext(), resolveStorageKeyDeclaration()

import { EgressDeniedError, isEgressAllowed } from '@ekanos/sdk/context';

​

Testing: @ekanos/sdk/testing

• createMockContext() — in-memory context with schema validation and egress enforcement
• invokeWebhook() — run a webhook handler with payload validation
• invokeSchedule() — run a schedule handler
• invokeActivate() — run an activation hook
• createMockFetchProvider() — fixture-backed fetch for widget tests
• Types for recording fetch calls and logs

import { createMockContext, invokeWebhook } from '@ekanos/sdk/testing';

​

Integration: @ekanos/sdk/integration

• defineIntegration() — define your integration (validates at import time)
• validateIntegrationDefinitions() — batch validation and collision detection
• IntegrationDefinitionSchema — the canonical zod schema
• Definition types: PartnerToolModule, PartnerWidgetDeclaration, PartnerWebhookDeclaration, PartnerScheduleDeclaration, PartnerOAuthDeclaration, PartnerActionDeclaration, WebhookSignatureScheme, OnActivateHandler, and related types
• parseCronExpression() — validate 5-field cron syntax
• PublicActionError — throw from an action handler to show its message to the user verbatim

import { defineIntegration } from '@ekanos/sdk/integration';
import type { PartnerToolModule } from '@ekanos/sdk/integration';

​

MCP: @ekanos/sdk/mcp — NOT PUBLISHED

​

Import patterns

// Types only — safe from client code
import type { IntegrationContext, IntegrationMetadata } from '@ekanos/sdk';

// Client components
import { Widget } from '@ekanos/sdk/components';

// Client hooks
import { useActivateIntegration } from '@ekanos/sdk/hooks';

// Error classes and matchers (isomorphic)
import { EgressDeniedError } from '@ekanos/sdk/context';

// Authoring (isomorphic)
import { defineIntegration } from '@ekanos/sdk/integration';

// Testing
import { createMockContext } from '@ekanos/sdk/testing';

​

Summary table

​

Next steps

• Storage — schema-validated state
• Tools — assistant-callable functions
• Widgets — dashboard components
• Testing — write unit tests