Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

9.1 KB
Raw Blame
import type {
  ChannelBinding,
  ChannelBindingStatus,
  ChannelFailureCategory,
  ChannelProvider,
  ProjectId,
} from "@akeru/contracts";

import { createTranslator, type MessageKey, type TranslationParams } from "./i18n/index.ts";

type ProjectRef = { readonly id: ProjectId };

export function channelProviderLabel(provider: ChannelProvider): string {
  if (provider === "imessage") return "iMessage";

  if (provider === "whatsapp") return "WhatsApp";

  if (provider === "telegram") return "Telegram";

  if (provider === "slack") return "Slack";

  return "Discord";
}

export type ChannelTranslate = (message: MessageKey, params?: TranslationParams) => string;

const englishTranslate: ChannelTranslate = createTranslator("en").t;

/**
 * Why a channel connection failed, in words a user can act on. Every category the server sends
 * has a sentence naming the provider, so clients never show a bare "could not connect".
 */
export function channelFailureReason(
  category: ChannelFailureCategory,
  provider: ChannelProvider,
  t: ChannelTranslate = englishTranslate,
): string {
  if (category === "credentials") {
    switch (provider) {
      case "telegram":
        return t("Telegram rejected the bot token.");
      case "slack":
        return t("Slack rejected the bot token or app token.");
      case "discord":
        return t("Discord rejected the bot token.");
      case "whatsapp":
        return t("WhatsApp rejected the access token.");
      case "imessage":
        return t("Photon rejected the connection credentials.");
    }
  }

  const name = channelProviderLabel(provider);

  switch (category) {
    case "network":
      return t("Could not reach {provider}. Check the network and try again.", { provider: name });
    case "project":
      return t("The project for this channel is unavailable. Choose another project.");
    case "delivery-unknown":
      return t("A reply may not have reached {provider}. Check the chat before replying again.", {
        provider: name,
      });
    case "restore":
      return t("{provider} did not reconnect after a restart. Reconnect to resume.", {
        provider: name,
      });
  }
}

export function channelHealthLabel(status: ChannelBindingStatus): string {
  switch (status) {
    case "connecting":
      return "Connecting";
    case "connected":
      return "Connected";
    case "disconnected":
      return "Disconnected";
    case "needs-reconnect":
      return "Reconnect required";
    case "failed":
      return "Connection failed";
    case "blocked":
      return "Choose another project";
    case "not-live":
      return "Not live";
  }
}

/** The single repair a client offers for a binding. */
export type ChannelRepairAction =
  | "none"
  | "wait"
  | "connect"
  | "reconnect"
  | "update-credentials"
  | "choose-project"
  | "check-delivery"
  | "configure-public-url";

/**
 * Picks one repair action from status and failure category. With `liveProjects`, a binding whose
 * project is gone asks for a project first, because every other repair would start it there.
 */
export function channelRepairAction(
  binding: Pick<ChannelBinding, "status" | "projectId" | "failureCategory">,
  liveProjects?: ReadonlyArray<ProjectRef>,
): ChannelRepairAction {
  if (binding.status === "connecting") return "wait";

  if (binding.status === "not-live") return "configure-public-url";

  if (
    binding.status === "blocked" ||
    binding.failureCategory === "project" ||
    (liveProjects && channelBindingNeedsProject(binding, liveProjects))
  ) {
    return "choose-project";
  }

  if (
    binding.failureCategory === "delivery-unknown" &&
    (binding.status === "connected" || binding.status === "failed")
  ) {
    return "check-delivery";
  }

  switch (binding.status) {
    case "connected":
      // A connected binding with a failure means a later attempt or reply failed while the
      // running transport stayed up. Offer the repair for that failure.
      switch (binding.failureCategory) {
        case "credentials":
          return "update-credentials";
        case "network":
        case "restore":
          return "reconnect";
        default:
          return "none";
      }

    // Rejected credentials would fail again, so every idle state asks for new ones first.
    case "disconnected":
      return binding.failureCategory === "credentials" ? "update-credentials" : "connect";
    case "needs-reconnect":
      return binding.failureCategory === "credentials" ? "update-credentials" : "reconnect";
    case "failed":
      return binding.failureCategory === "credentials" ? "update-credentials" : "reconnect";
  }
}

export function channelRepairLabel(action: ChannelRepairAction): string | null {
  switch (action) {
    case "none":
      return null;
    case "wait":
      return "Connecting…";
    case "connect":
      return "Connect";
    case "reconnect":
      return "Reconnect";
    case "update-credentials":
      return "Update credentials";
    case "choose-project":
      return "Choose project";
    case "check-delivery":
      return "Check the channel";
    case "configure-public-url":
      return "Set a public URL";
  }
}

export function channelBindingPresentation(
  binding: ChannelBinding,
  projects: ReadonlyArray<{ readonly id: ProjectId; readonly title: string }>,
) {
  const deliveredCount = new Set(binding.sentMessageIds).size;
  const needsProject = channelBindingNeedsProject(binding, projects);

  return {
    provider: channelProviderLabel(binding.provider),
    health: channelHealthLabel(binding.status),
    needsProjectConfirmation: needsProject,
    warning: needsProject
      ? "Choose a project before reconnecting"
      : binding.lastError
        ? "Channel needs attention"
        : null,
    project: binding.projectId
      ? (projects.find((project) => project.id === binding.projectId)?.title ??
        "Project unavailable")
      : "No project selected",
    delivery:
      deliveredCount === 0
        ? "No confirmed deliveries"
        : `${deliveredCount} confirmed ${deliveredCount === 1 ? "delivery" : "deliveries"}`,
  };
}

/** Where a failed reassignment puts the channel back: its old project while live, else the attempted one. */
export function channelRestoreProjectId(
  previousProjectId: ProjectId | undefined,
  attemptedProjectId: ProjectId,
  liveProjects: ReadonlyArray<ProjectRef>,
): ProjectId {
  return previousProjectId && liveProjects.some((project) => project.id === previousProjectId)
    ? previousProjectId
    : attemptedProjectId;
}

/** A binding needs a new project when the server blocked it or its project is no longer live. */
export function channelBindingNeedsProject(
  binding: Pick<ChannelBinding, "status" | "projectId">,
  liveProjects: ReadonlyArray<ProjectRef>,
): boolean {
  return (
    binding.status === "blocked" ||
    !binding.projectId ||
    !liveProjects.some((project) => project.id === binding.projectId)
  );
}

/**
 * The project a channel picker shows. An explicit choice wins, then the binding's own live project,
 * then the hint (usually `defaultProjectIdForBot`). Returns null when no live project applies, so
 * callers keep attach and repair disabled until the user picks one.
 */
export function channelPickerProjectId(input: {
  readonly selected: ProjectId | null | undefined;
  readonly binding: Pick<ChannelBinding, "status" | "projectId"> | undefined;
  readonly hint: ProjectId | null;
  readonly liveProjects: ReadonlyArray<ProjectRef>;
}): ProjectId | null {
  const live = (id: ProjectId | null | undefined): id is ProjectId =>
    !!id && input.liveProjects.some((project) => project.id === id);

  if (live(input.selected)) return input.selected;

  if (input.binding && !channelBindingNeedsProject(input.binding, input.liveProjects)) {
    return input.binding.projectId ?? null;
  }

  return live(input.hint) ? input.hint : null;
}

/** Whether the picked project differs from where the binding runs, or repairs a blocked binding. */
export function canChangeChannelProject(
  binding: Pick<ChannelBinding, "status" | "projectId">,
  pickedProjectId: ProjectId | null,
  liveProjects: ReadonlyArray<ProjectRef>,
): pickedProjectId is ProjectId {
  // Moving starts the channel, so a disconnected channel stays put until it is reconnected,
  // unless its project is gone and choosing a new one is the only repair.
  if (binding.status === "disconnected" && !channelBindingNeedsProject(binding, liveProjects)) {
    return false;
  }

  if (!pickedProjectId || !liveProjects.some((project) => project.id === pickedProjectId)) {
    return false;
  }

  return channelBindingNeedsProject(binding, liveProjects) || pickedProjectId !== binding.projectId;
}

/**
 * The project a reconnect should start a disconnected binding in when the picker shows another
 * live project. Null means reconnect where the binding already runs.
 */
export function channelReconnectProject(
  binding: Pick<ChannelBinding, "status" | "projectId">,
  pickedProjectId: ProjectId | null,
  liveProjects: ReadonlyArray<ProjectRef>,
): ProjectId | null {
  return binding.status === "disconnected" &&
    pickedProjectId !== null &&
    pickedProjectId !== binding.projectId &&
    liveProjects.some((project) => project.id === pickedProjectId)
    ? pickedProjectId
    : null;
}