@dbx-tools/shared-teams 0.3.39

package/README.md

@@ -0,0 +1,73 @@
+# @dbx-tools/shared-teams
+
+Browser-safe Adaptive Card and Bot Framework activity schemas (plus inferred
+types) for the Teams add-on.
+
+Import this package when a UI, Mastra tool schema, server route, or test needs
+to validate the same Adaptive Card payloads that
+[`@dbx-tools/teams`](../../node/teams) builds and
+[`@dbx-tools/ui-teams`](../../ui/teams) renders.
+
+Key features:
+
+- High-level `CardSpec` contract - the small, model-friendly vocabulary a model
+  drafts (title, subtitle, text, facts, link actions) instead of hand-authoring
+  raw Adaptive Card JSON.
+- `AdaptiveCard` envelope schema for the compiled Adaptive Card 1.5 document the
+  `adaptivecards` renderer consumes and Teams accepts.
+- `CardResult` schema for the build response returned to a model or a browser.
+- `Activity` contract for the conversation endpoint - the Bot Framework envelope
+  a Teams channel exchanges, with `CardAttachment` tagging a card as
+  `application/vnd.microsoft.card.adaptive`, plus the `toCardAttachment` /
+  `cardsOf` helpers both sides use so attachments are wrapped and read
+  identically. Unknown activity fields are preserved rather than stripped, since
+  a real channel sends far more than this reads.
+- Model/tool-friendly schemas that avoid JSON Schema constraints known to cause
+  problems with some serving endpoints (no array `minItems`).
+
+## Validate A Drafted Card
+
+```ts
+import { card, type CardSpec } from "@dbx-tools/shared-teams";
+
+const spec: CardSpec = card.cardSpecSchema.parse({
+  title: "Deployment succeeded",
+  subtitle: "prod • 2m ago",
+  text: "The **api** service rolled out cleanly.",
+  facts: [
+    { title: "Version", value: "1.4.2" },
+    { title: "Owner", value: "alice" },
+  ],
+  actions: [{ title: "View run", url: "https://example.com/runs/42" }],
+});
+```
+
+The spec schema is intentionally small so a model produces valid input rather
+than free-form card JSON the renderer would reject.
+
+## Validate A Compiled Card
+
+```ts
+const result = card.cardResultSchema.parse(await response.json());
+// result.card is a full Adaptive Card document ready to render or post to Teams.
+```
+
+`adaptiveCardSchema` pins the envelope every consumer relies on (`type`,
+`$schema`, `version`, `body`); the builder in `@dbx-tools/teams` owns the exact
+element shapes inside `body` / `actions`.
+
+## Modules
+
+- `card` - `cardFactSchema`, `cardActionSchema`, `cardSpecSchema`,
+  `adaptiveCardSchema`, `cardResultSchema`, the `ADAPTIVE_CARD_VERSION` /
+  `ADAPTIVE_CARD_SCHEMA_URL` constants, and flat inferred types: `CardFact`,
+  `CardAction`, `CardSpec`, `AdaptiveCard`, and `CardResult`.
+- `activity` - `activitySchema`, `activityRequestSchema`,
+  `activityResponseSchema`, `cardAttachmentSchema`, `channelAccountSchema`,
+  `conversationAccountSchema`, the `ADAPTIVE_CARD_CONTENT_TYPE` /
+  `ACTIVITY_TYPES` constants, the `toCardAttachment` / `cardsOf` helpers, and
+  the `Activity`, `ActivityRequest`, `ActivityResponse`, `CardAttachment`,
+  `ChannelAccount`, `ConversationAccount`, and `ActivityType` types.
+
+The schemas intentionally avoid array `.min()` constraints so they can be reused
+as model/tool JSON schemas for serving endpoints that reject `minItems`.

package/index.ts

@@ -0,0 +1,8 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as activity from "./src/activity";
+export * as card from "./src/card";
+export type { ActivityType, ChannelAccount, ConversationAccount, CardAttachment, Activity, ActivityRequest, ActivityResponse } from "./src/activity";
+export type { CardFact, CardAction, CardSpec, AdaptiveCard, CardResult } from "./src/card";

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@dbx-tools/shared-teams",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/shared/teams"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "zod": "4.3.6",
+    "@dbx-tools/shared-core": "0.3.39"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.39",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "dbxToolsConfig": {
+    "tags": [
+      "shared"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/activity.ts

@@ -0,0 +1,145 @@
+/**
+ * Wire-format contract for the Teams conversation endpoint: the Bot Framework
+ * `Activity` a Teams-like client posts, and the activity (carrying Adaptive Card
+ * attachments) the agent answers with.
+ *
+ * Why this shape rather than a bespoke `{ message }` envelope: Teams does not
+ * speak a custom chat API. A channel delivers a bot a JSON `Activity` and reads
+ * back activities whose `attachments` carry
+ * `application/vnd.microsoft.card.adaptive` payloads. Modelling the real
+ * protocol here means the same endpoint that backs the in-repo preview chat is
+ * the one a Bot Framework channel could call - the analogue of how the Mastra
+ * plugin exposes MCP at a path rather than inventing a tool-call API.
+ *
+ * Only the subset the conversation endpoint actually reads or writes is
+ * modelled. `Activity` is a large, evolving envelope, so unknown fields are
+ * PRESERVED rather than stripped (see {@link activitySchema}) - a channel sends
+ * far more than this, and dropping it would corrupt a round-trip.
+ *
+ * @module
+ */
+
+import { z } from "zod";
+import { adaptiveCardSchema } from "./card";
+
+/** The attachment content type Teams uses for an Adaptive Card. */
+export const ADAPTIVE_CARD_CONTENT_TYPE = "application/vnd.microsoft.card.adaptive";
+
+/** Bot Framework activity types this endpoint understands. */
+export const ACTIVITY_TYPES = ["message", "conversationUpdate", "typing"] as const;
+
+/** A Bot Framework activity type. */
+export type ActivityType = (typeof ACTIVITY_TYPES)[number];
+
+/**
+ * A participant in a conversation. `id` is the stable key; `name` is the
+ * display label a chat transcript shows.
+ */
+export const channelAccountSchema = z.object({
+  id: z.string().describe("Stable id of the user or bot."),
+  name: z.string().optional().describe("Display name shown in the transcript."),
+});
+
+/** A conversation participant (user or bot). */
+export type ChannelAccount = z.infer<typeof channelAccountSchema>;
+
+/**
+ * The conversation an activity belongs to. The `id` is what maps onto a Mastra
+ * memory thread, so a client that keeps sending the same id gets a continuous
+ * conversation.
+ */
+export const conversationAccountSchema = z.object({
+  id: z.string().describe("Conversation id; maps to the agent's memory thread."),
+});
+
+/** The conversation an activity belongs to. */
+export type ConversationAccount = z.infer<typeof conversationAccountSchema>;
+
+/**
+ * An Adaptive Card attachment - how a card reaches a Teams client. The card
+ * document lives under `content`, tagged by `contentType`.
+ */
+export const cardAttachmentSchema = z.object({
+  contentType: z.literal(ADAPTIVE_CARD_CONTENT_TYPE),
+  content: adaptiveCardSchema.describe("The compiled Adaptive Card document."),
+});
+
+/** An Adaptive Card attachment on an activity. */
+export type CardAttachment = z.infer<typeof cardAttachmentSchema>;
+
+/**
+ * A Bot Framework activity.
+ *
+ * `.passthrough()` is deliberate: a real channel sends `channelId`,
+ * `serviceUrl`, `timestamp`, `replyToId`, `channelData` and more. This endpoint
+ * reads only what it needs, but an unknown field is part of the caller's
+ * envelope and is kept so a client can round-trip its own metadata.
+ */
+export const activitySchema = z
+  .object({
+    type: z.enum(ACTIVITY_TYPES).describe("Activity type; `message` carries user text."),
+    id: z.string().optional().describe("Activity id, assigned by the sender."),
+    text: z.string().optional().describe("Message text, present on a `message` activity."),
+    from: channelAccountSchema.optional().describe("Who sent the activity."),
+    recipient: channelAccountSchema.optional().describe("Who the activity is addressed to."),
+    conversation: conversationAccountSchema
+      .optional()
+      .describe("Conversation the activity belongs to."),
+    attachments: z
+      .array(cardAttachmentSchema)
+      .optional()
+      .describe("Adaptive Card attachments carried by the activity."),
+    timestamp: z.string().optional().describe("ISO-8601 time the activity was created."),
+  })
+  .passthrough();
+
+/** A Bot Framework activity. */
+export type Activity = z.infer<typeof activitySchema>;
+
+/**
+ * The request body the conversation endpoint accepts: an inbound activity plus
+ * optional routing hints that are NOT part of the Bot Framework envelope
+ * (which agent to run, which serving model to use). Keeping them as siblings of
+ * `activity` leaves the protocol payload untouched.
+ */
+export const activityRequestSchema = z.object({
+  activity: activitySchema.describe("The inbound Bot Framework activity."),
+  agentId: z
+    .string()
+    .optional()
+    .describe("Mastra agent to answer with. Defaults to the plugin's default agent."),
+  model: z.string().optional().describe("Optional serving-endpoint override for this turn."),
+});
+
+/** A request to the Teams conversation endpoint. */
+export type ActivityRequest = z.infer<typeof activityRequestSchema>;
+
+/**
+ * The endpoint's response: the activities to append to the transcript. An array
+ * because one turn may answer with several activities (Teams itself allows a
+ * bot to send more than one reply), and because a future streaming/typing
+ * variant can grow into the same shape without a breaking change.
+ */
+export const activityResponseSchema = z.object({
+  activities: z.array(activitySchema).describe("Activities the bot replies with."),
+});
+
+/** The response from the Teams conversation endpoint. */
+export type ActivityResponse = z.infer<typeof activityResponseSchema>;
+
+/**
+ * Wrap a compiled Adaptive Card as a Teams attachment.
+ *
+ * Browser-safe and shared so the server (building a reply) and any client
+ * (rendering an optimistic local activity) tag attachments identically.
+ */
+export const toCardAttachment = (card: z.infer<typeof adaptiveCardSchema>): CardAttachment => ({
+  contentType: ADAPTIVE_CARD_CONTENT_TYPE,
+  content: card,
+});
+
+/** Read the Adaptive Card documents carried by an activity, if any. */
+export const cardsOf = (activity: Activity): z.infer<typeof adaptiveCardSchema>[] =>
+  (activity.attachments ?? [])
+    .filter((attachment) => attachment.contentType === ADAPTIVE_CARD_CONTENT_TYPE)
+    .map((attachment) => attachment.content);

package/src/card.ts

@@ -0,0 +1,125 @@
+/**
+ * Wire-format contract for the Teams add-on: the semantic card a model drafts
+ * and the Adaptive Card document that drafting compiles to. Pure (zod +
+ * inferred types, no Node-only imports) so the server-side card builder, the
+ * Mastra tool, and the React Adaptive Cards renderer all validate / type
+ * against one definition.
+ *
+ * The model does NOT hand-author raw Adaptive Card JSON. It describes a card in
+ * a small, high-level vocabulary ({@link CardSpec}) - a title, some text/fact
+ * blocks, and optional link actions - and the builder compiles that into a
+ * valid Adaptive Card 1.5 document ({@link AdaptiveCard}). Keeping the model's
+ * surface small avoids the two failure modes of free-form card JSON: an invalid
+ * schema the renderer rejects, and a card that renders but ignores Teams' host
+ * constraints.
+ *
+ * Array fields intentionally avoid `.min()` / `.nonempty()`: those emit
+ * `minItems` in the JSON schema, which some Model Serving endpoints reject
+ * ("array types do not support minItems") when the schema is forwarded as a
+ * tool definition.
+ *
+ * @module
+ */
+
+import { z } from "zod";
+
+/** The Adaptive Card schema version the builder targets. Teams supports 1.5. */
+export const ADAPTIVE_CARD_VERSION = "1.5";
+
+/** The Adaptive Card `$schema` URL a well-formed document declares. */
+export const ADAPTIVE_CARD_SCHEMA_URL = "http://adaptivecards.io/schemas/adaptive-card.json";
+
+/**
+ * A single labelled fact, rendered as a row in an Adaptive Card `FactSet`.
+ * Facts are the right shape for compact key/value detail (status, owner, due
+ * date) that would be noise as prose.
+ */
+export const cardFactSchema = z.object({
+  title: z.string().describe('Fact label shown on the left (e.g. "Status", "Owner").'),
+  value: z.string().describe('Fact value shown on the right (e.g. "Open", "alice").'),
+});
+
+/** A labelled key/value fact in a {@link CardSpec}. */
+export type CardFact = z.infer<typeof cardFactSchema>;
+
+/**
+ * An action button rendered under the card body. Only an open-URL action is
+ * modelled: it is the one action that is safe to render in any host without a
+ * back-end wired up, and it covers the common "here is the link" case.
+ */
+export const cardActionSchema = z.object({
+  title: z.string().describe('Button label (e.g. "Open ticket", "View run").'),
+  url: z
+    .string()
+    .describe("Absolute https URL the button opens when tapped (an Action.OpenUrl target)."),
+});
+
+/** A link action button in a {@link CardSpec}. */
+export type CardAction = z.infer<typeof cardActionSchema>;
+
+/**
+ * The high-level card a model asks to build (the tool input). Deliberately
+ * small: a heading, optional supporting text, optional facts, and optional link
+ * buttons. The builder turns this into a full Adaptive Card document.
+ */
+export const cardSpecSchema = z.object({
+  title: z.string().describe("Card heading, shown bold at the top of the card."),
+  subtitle: z
+    .string()
+    .optional()
+    .describe("Optional lighter subheading under the title (e.g. a category or timestamp)."),
+  text: z
+    .string()
+    .optional()
+    .describe(
+      [
+        "Optional body text under the heading. A limited Markdown subset is",
+        "supported by the Teams host: **bold**, _italic_, links, and '-' bullet",
+        "lists. Do NOT use headings, tables, or fenced code blocks - use the",
+        "`facts` array for tabular key/value detail instead.",
+      ].join(" "),
+    ),
+  facts: z
+    .array(cardFactSchema)
+    .optional()
+    .describe("Optional key/value rows rendered as a FactSet (label on the left, value right)."),
+  actions: z
+    .array(cardActionSchema)
+    .optional()
+    .describe("Optional link buttons rendered under the body, each opening a URL."),
+});
+
+/** The validated semantic card a model asked to build. */
+export type CardSpec = z.infer<typeof cardSpecSchema>;
+
+/**
+ * The compiled Adaptive Card document - the JSON the `adaptivecards` renderer
+ * consumes. Typed loosely (`elements` / `actions` as record arrays) because the
+ * full Adaptive Card schema is large and host-versioned; the builder owns the
+ * exact element shapes and this contract only pins the envelope every consumer
+ * relies on (`type`, `version`, `body`).
+ */
+export const adaptiveCardSchema = z.object({
+  type: z.literal("AdaptiveCard"),
+  $schema: z.string(),
+  version: z.string(),
+  body: z.array(z.record(z.string(), z.unknown())),
+  actions: z.array(z.record(z.string(), z.unknown())).optional(),
+});
+
+/** A compiled Adaptive Card document ready to render or post to Teams. */
+export type AdaptiveCard = z.infer<typeof adaptiveCardSchema>;
+
+/**
+ * The result the card tool returns: the compiled Adaptive Card plus the
+ * `title` echoed back for a caller that wants a label without re-reading the
+ * document. Kept separate from {@link AdaptiveCard} so the tool output stays
+ * additive.
+ */
+export const cardResultSchema = z.object({
+  title: z.string().describe("The card title, echoed for convenience."),
+  card: adaptiveCardSchema.describe("The compiled Adaptive Card document."),
+});
+
+/** The result of building a card. */
+export type CardResult = z.infer<typeof cardResultSchema>;