@zhin.js/im-contract

@zhin.js/im-contract is the zero-dependency, transport-neutral contract for Zhin IM integrations. It provides stable identities and delivery semantics without importing Plugin Runtime, a platform SDK, or an AI package.

Why this package exists

Adapters historically exchanged strings such as group:123 and occasionally combined a target with a message id. That makes a colon in a native id, a thread, or a cross-platform operation ambiguous. Framework code now uses these structured values instead:

• ConversationRef: endpoint-bound conversation identity;
• ActorRef: stable platform user identity, distinct from a display name;
• MessageRef: a native message id within a conversation;
• DeliveryReceipt: serializable outcome of an attempted outbound delivery;
• EndpointCapabilities: declared operations rather than optional-method detection.

Adapters carry ConversationRef and MessageRef unchanged until their native protocol boundary. Framework packages do not encode compound string identities.

Example

import type {
  ConversationRef,
  DeliveryReceipt,
  EndpointCapabilities,
} from '@zhin.js/im-contract';

const capabilities: EndpointCapabilities = {
  inbound: true,
  outbound: true,
  operations: { recall: true },
};

const conversation: ConversationRef = {
  endpoint: { adapter: 'telegram', id: 'telegram~primary' },
  kind: 'group',
  id: '-100123',
};

const receipt: DeliveryReceipt = { status: 'sent' };

Guarantees

• The package has no runtime dependencies.
• Native identifiers are opaque strings and are never split or normalized.
• ActorRef.id is suitable for authorization and session keys; displayName is presentation-only.
• DeliveryReceipt contains serializable data only, so it can cross Console, HTTP, MCP, A2A, and activity-feedback boundaries.
• Conversation consumers depend on ConversationEventReader; only the owning runtime and persistence adapter require the combined ConversationEventStore writer contract.

Source map

The package keeps a shallow layout and a one-way dependency direction:

| File | Responsibility | | --- | --- | | identity.ts | Endpoint, conversation, actor, and message identities | | segment.ts | Canonical segment/media contracts and zero-dependency guards | | conversation.ts | Conversation messages, references, and event facts | | conversation-store.ts | Reader/writer ports and in-memory/database event-store implementations | | endpoint.ts | Endpoint capabilities and delivery receipts | | index.ts | Stable package facade; contains no implementation |

Higher layers should import transport-neutral values from this package instead of reaching through @zhin.js/core.

Development

pnpm --filter @zhin.js/im-contract test
pnpm --filter @zhin.js/im-contract build