Docs: Example apps

Example apps

Two small apps in the repository's examples/ folder, built only on the typed client (@carechannel/client) and Hono. Both are tested against the real API in CI, so they keep working as CareChannel changes.

Internal “log feedback” form

For support and sales: enter what a customer asked for. It looks for a similar post and adds the customer's vote with a priority and an internal note, or posts a new idea on their behalf. Runs on your server with an API key that has the core and triage toolsets.

CARECHANNEL_URL=https://ballot.jumpstartsolutions.co CARECHANNEL_WORKSPACE=acme CARECHANNEL_API_KEY=cc_sk_… \
  pnpm --filter @carechannel/example-log-feedback start
examples/log-feedback/src/app.ts
/**
 * Example bespoke app (ROADMAP M6.5): an internal "log feedback" form for a support or sales
 * team. It runs on your own server with a CareChannel API key and uses only the typed client:
 * it checks for a similar post first and adds the customer's vote (with priority and a
 * note) instead of creating a duplicate, or posts a new idea on the customer's behalf.
 */
import { CareChannelApiError, type CareChannelClient } from "@carechannel/client";
import { Hono } from "hono";
import { html } from "hono/html";

/** Above this, find_similar_posts' match is treated as the same idea. */
const SAME_IDEA = 0.5;

const page = (body: ReturnType<typeof html>) =>
  html`<!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <title>Log customer feedback</title>
        <style>
          body {
            font:
              15px/1.5 system-ui,
              sans-serif;
            max-width: 36rem;
            margin: 2rem auto;
            padding: 0 1rem;
          }
          label {
            display: grid;
            gap: 0.25rem;
            margin-bottom: 0.75rem;
          }
          input,
          textarea,
          select,
          button {
            font: inherit;
            padding: 0.4rem;
          }
        </style>
      </head>
      <body>
        ${body}
      </body>
    </html>`;

export function logFeedbackApp(careChannel: CareChannelClient): Hono {
  const app = new Hono();

  app.get("/", async (c) => {
    const { items: boards } = await careChannel.list_boards();
    return c.html(
      page(
        html`<h1>Log customer feedback</h1>
          <form method="post">
            <label>Customer email <input name="email" type="email" required /></label>
            <label>Customer name <input name="name" /></label>
            <label>What they asked for <input name="title" required maxlength="200" /></label>
            <label>Details (internal note) <textarea name="details" rows="4"></textarea></label>
            <label
              >Board
              <select name="board">
                ${boards.map((b) => html`<option value="${b.slug}">${b.name}</option>`)}
              </select>
            </label>
            <label
              >How much it matters
              <select name="priority">
                <option value="nice_to_have">Nice to have</option>
                <option value="important">Important</option>
                <option value="must_have">Must have</option>
              </select>
            </label>
            <button>Log it</button>
          </form>`,
      ),
    );
  });

  app.post("/", async (c) => {
    const form = await c.req.parseBody();
    const field = (name: string) => String(form[name] ?? "").trim();
    const customer = { email: field("email"), ...(field("name") ? { name: field("name") } : {}) };
    const priority = field("priority") as "nice_to_have" | "important" | "must_have";
    try {
      const { items } = await careChannel.find_similar_posts({
        title: field("title"),
        board: field("board"),
      });
      const match = items[0];
      if (match && match.similarity >= SAME_IDEA) {
        await careChannel.add_vote_on_behalf({
          post: match.post.id,
          user: customer,
          priority,
          ...(field("details") ? { note: field("details") } : {}),
        });
        return c.html(
          page(
            html`<h1>Vote added</h1>
              <p>
                ${customer.email} now votes for
                <a href="${match.post.admin_url ?? match.post.portal_url}">${match.post.title}</a>.
              </p>
              <p><a href="/">Log more</a></p>`,
          ),
        );
      }
      const post = await careChannel.create_post(
        {
          board: field("board"),
          title: field("title"),
          ...(field("details") ? { body: field("details") } : {}),
          on_behalf_of: customer,
        },
        { idempotencyKey: `${customer.email}:${field("title")}` },
      );
      await careChannel.add_vote_on_behalf({ post: post.id, user: customer, priority });
      return c.html(
        page(
          html`<h1>New idea posted</h1>
            <p><a href="${post.admin_url ?? post.portal_url}">${post.title}</a></p>
            <p><a href="/">Log more</a></p>`,
        ),
      );
    } catch (error) {
      if (!(error instanceof CareChannelApiError)) throw error;
      return c.html(
        page(
          html`<h1>Couldn't log that</h1>
            <p>${error.message}</p>
            <p><a href="/">Try again</a></p>`,
        ),
        400,
      );
    }
  });

  return app;
}

Custom read-only roadmap page

Your public roadmap in your own design, on your own site. Public reads need no credentials, so there's no key to protect.

CARECHANNEL_URL=https://ballot.jumpstartsolutions.co CARECHANNEL_WORKSPACE=acme \
  pnpm --filter @carechannel/example-roadmap-page start
examples/roadmap-page/src/app.ts
/**
 * Example bespoke app (ROADMAP M6.5): a custom read-only roadmap page for your own site. It
 * reads the public roadmap with the typed client and no credentials (public reads don't need
 * one) and renders it in your own design. Escaping is done by Hono's html helper.
 */
import type { CareChannelClient } from "@carechannel/client";
import { Hono } from "hono";
import { html } from "hono/html";

export function roadmapPageApp(
  careChannel: CareChannelClient,
  options: { title?: string } = {},
): Hono {
  const app = new Hono();
  app.get("/", async (c) => {
    const roadmap = await careChannel.get_public_roadmap();
    const title = options.title ?? "What we're working on";
    const columns = roadmap.enabled
      ? roadmap.columns.map(
          (column) =>
            html`<section>
              <h2>
                <span class="dot" style="background:${column.status.color}"></span>
                ${column.status.name} <small>${column.total}</small>
              </h2>
              <ul>
                ${column.posts.map(
                  (post) =>
                    html`<li>
                      <a href="${post.portal_url}">${post.title}</a>
                      <small>${post.vote_count} vote${post.vote_count === 1 ? "" : "s"}</small>
                    </li>`,
                )}
              </ul>
            </section>`,
        )
      : html`<p>The roadmap isn't public right now.</p>`;
    return c.html(
      html`<!doctype html>
        <html lang="en">
          <head>
            <meta charset="utf-8" />
            <title>${title}</title>
            <style>
              body {
                font:
                  15px/1.5 system-ui,
                  sans-serif;
                margin: 2rem;
              }
              main {
                display: grid;
                grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
                gap: 1rem;
              }
              section {
                background: #f5f5f7;
                border-radius: 10px;
                padding: 1rem;
              }
              ul {
                list-style: none;
                padding: 0;
                display: grid;
                gap: 0.5rem;
              }
              li {
                background: #fff;
                border-radius: 8px;
                padding: 0.6rem;
                display: grid;
              }
              .dot {
                display: inline-block;
                width: 0.6rem;
                height: 0.6rem;
                border-radius: 50%;
              }
            </style>
          </head>
          <body>
            <h1>${title}</h1>
            <main>${columns}</main>
          </body>
        </html>`,
    );
  });
  return app;
}