Backends

import { mintSession } from "@coworkkit/server";

// COWORKKIT_API_KEY stays on the server — the browser only receives the short-lived token.
// `userId` is the user the agent acts as. "dev-user" is fine while developing; in production
// derive it from your own auth/session middleware, server-side — never from the client.
app.post("/api/session", async (_req, res) => {
  try {
    const session = await mintSession(process.env.COWORKKIT_API_KEY!, { userId: "dev-user" });
    res.json(session);
  } catch (err) {
    res.status(502).json({ error: err instanceof Error ? err.message : "session mint failed" });
  }
});

POST {base}/session         base: env COWORKKIT_CLOUD_URL, default https://api.coworkkit.ai

  header   x-api-key: <your secret tenant key>      (never logged, never in the browser)
  header   content-type: application/json
  body     {"userId": "<derived server-side from your own auth>"}

-> 2xx      {"token": "...", "serverUrl": "...", "cloudUrl": "..."}   relay UNCHANGED to getToken
-> 4xx/5xx  {"error": "...", "reason": "..."}                         reason optional; relay the status

<?php
// Coworkkit — mint a voice session from PHP (bring-your-own-backend).
// The whole server side of the closed loop: hold the secret key, POST /session,
// relay the JSON. Framework-free, ext-curl only, PHP >= 8.1. See backends/README.md.

/** Thrown when /session returns a non-2xx status or a non-JSON body. */
class CoworkkitException extends \RuntimeException
{
    public function __construct(
        string $message,
        public readonly ?int $status = null,
        public readonly ?string $reason = null,
    ) {
        parent::__construct($message);
    }
}

/**
 * Mint a session. Derive $userId from YOUR OWN auth, server-side — never trust the
 * browser (KB-0001). Returns the decoded body unchanged, so unknown fields survive.
 */
function coworkkit_mint(string $userId): array
{
    $base = getenv('COWORKKIT_CLOUD_URL') ?: 'https://api.coworkkit.ai';
    $apiKey = getenv('COWORKKIT_API_KEY') ?: '';

    $ch = curl_init("{$base}/session");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5, // a stalled upstream must not pin this worker forever
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => ['content-type: application/json', "x-api-key: {$apiKey}"],
        CURLOPT_POSTFIELDS => json_encode(['userId' => $userId]),
    ]);
    $text = curl_exec($ch);
    $curlErr = $text === false ? curl_error($ch) : null;
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    // (No curl_close: the CurlHandle frees itself when it goes out of scope; the call
    // is a deprecated no-op since PHP 8.0.)

    $body = json_decode((string) $text, true);
    $ok = is_array($body);
    if ($status < 200 || $status >= 300 || !$ok) {
        // Transport failure or non-JSON (HTML error/placeholder) fails clearly —
        // never an unhandled parse crash.
        $detail = $ok && isset($body['error'])
            ? (string) $body['error']
            : ($curlErr !== null
                ? "unreachable: {$curlErr} — is the service deployed/reachable?"
                : 'non-JSON response — is the service deployed/reachable?');
        $reason = $ok && isset($body['reason']) && is_string($body['reason']) ? $body['reason'] : null;
        throw new CoworkkitException("Coworkkit /session failed (HTTP {$status}): {$detail}", $status, $reason);
    }
    return $body; // relay unchanged — the contract grows additively
}

"""Coworkkit — mint a voice session from Python (bring-your-own-backend).

The whole server side of the closed loop: hold the secret key, POST /session,
relay the JSON. Stdlib only (urllib), Python 3.8+ — no pip dependency.
See backends/README.md.
"""

from __future__ import annotations

import json
import os
import urllib.error
import urllib.request


class CoworkkitError(Exception):
    """Raised when /session returns a non-2xx status or a non-JSON body."""

    def __init__(self, message: str, status: int | None = None, reason: str | None = None):
        super().__init__(message)
        self.status = status
        self.reason = reason


def mint_session(user_id: str) -> dict:
    """Mint a session. Derive user_id from YOUR OWN auth, server-side (KB-0001).

    Returns the decoded body unchanged, so unknown fields survive.
    """
    base = os.environ.get("COWORKKIT_CLOUD_URL") or "https://api.coworkkit.ai"
    req = urllib.request.Request(
        f"{base}/session",
        data=json.dumps({"userId": user_id}).encode(),
        headers={
            "content-type": "application/json",
            "x-api-key": os.environ.get("COWORKKIT_API_KEY", ""),
        },
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=15) as resp:  # noqa: S310 (fixed https scheme)
            status, text = resp.status, resp.read().decode()
    except urllib.error.HTTPError as exc:  # 4xx/5xx still carry a body
        status, text = exc.code, exc.read().decode()
    except urllib.error.URLError as exc:  # unreachable/timeout — typed error, never a raw traceback
        raise CoworkkitError(f"Coworkkit /session unreachable: {exc.reason} — is the service deployed/reachable?") from exc

    try:
        body = json.loads(text)
        ok = isinstance(body, dict)
    except ValueError:  # non-JSON (HTML error/placeholder) — never crash on parse
        body, ok = None, False

    if not 200 <= status < 300 or not ok:
        detail = str(body["error"]) if ok and "error" in body else "non-JSON response — is the service deployed/reachable?"
        reason = body.get("reason") if ok and isinstance(body.get("reason"), str) else None
        raise CoworkkitError(f"Coworkkit /session failed (HTTP {status}): {detail}", status, reason)
    return body  # relay unchanged — the contract grows additively

# Coworkkit — mint a voice session from Ruby (bring-your-own-backend).
# The whole server side of the closed loop: hold the secret key, POST /session,
# relay the JSON. Stdlib only (net/http). See backends/README.md.

require 'net/http'
require 'json'
require 'openssl' # referenced in the transport rescue even on plain-http runs
require 'uri'

# Raised when /session returns a non-2xx status or a non-JSON body.
class CoworkkitError < StandardError
  attr_reader :status, :reason

  def initialize(message, status = nil, reason = nil)
    super(message)
    @status = status
    @reason = reason
  end
end

# Mint a session. Derive user_id from YOUR OWN auth, server-side (KB-0001).
# Returns the parsed body unchanged, so unknown fields survive.
def coworkkit_mint(user_id)
  base = ENV['COWORKKIT_CLOUD_URL']
  base = 'https://api.coworkkit.ai' if base.nil? || base.empty?
  uri = URI("#{base}/session")

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = uri.scheme == 'https'
  http.open_timeout = 5  # a stalled upstream must not pin this thread forever
  http.read_timeout = 15
  req = Net::HTTP::Post.new(uri)
  req['content-type'] = 'application/json'
  req['x-api-key'] = ENV['COWORKKIT_API_KEY'] || ''
  req.body = JSON.generate('userId' => user_id)
  begin
    res = http.request(req)
  rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError, EOFError => e
    # Unreachable/timeout — typed error, never a raw exception out of the recipe.
    raise CoworkkitError, "Coworkkit /session unreachable: #{e.message} — is the service deployed/reachable?"
  end

  status = res.code.to_i
  begin
    body = JSON.parse(res.body)
    ok = body.is_a?(Hash)
  rescue JSON::ParserError # non-JSON (HTML error/placeholder) — never crash on parse
    body = nil
    ok = false
  end

  if status < 200 || status >= 300 || !ok
    detail = ok && body.key?('error') ? body['error'].to_s : 'non-JSON response — is the service deployed/reachable?'
    reason = ok && body['reason'].is_a?(String) ? body['reason'] : nil
    raise CoworkkitError.new("Coworkkit /session failed (HTTP #{status}): #{detail}", status, reason)
  end
  body # relay unchanged — the contract grows additively
end

// Package coworkkitmint mints Coworkkit voice sessions from Go
// (bring-your-own-backend). The whole server side of the closed loop: hold the
// secret key, POST /session, relay the JSON. Stdlib only. See backends/README.md.
package coworkkitmint

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

// http.DefaultClient never times out; a stalled upstream must not pin a goroutine forever.
var httpClient = &http.Client{Timeout: 15 * time.Second}

// CoworkkitError is returned when /session gives a non-2xx status or a non-JSON body.
type CoworkkitError struct {
	Status  int
	Reason  string
	Message string
}

func (e *CoworkkitError) Error() string { return e.Message }

// MintSession mints a session. Derive userID from YOUR OWN auth, server-side
// (KB-0001); apiKey is your secret tenant key. Returns the decoded body unchanged,
// so unknown fields survive.
func MintSession(apiKey, userID string) (map[string]any, error) {
	base := os.Getenv("COWORKKIT_CLOUD_URL")
	if base == "" {
		base = "https://api.coworkkit.ai"
	}
	payload, _ := json.Marshal(map[string]string{"userId": userID})
	req, err := http.NewRequest(http.MethodPost, base+"/session", bytes.NewReader(payload))
	if err != nil {
		return nil, &CoworkkitError{Message: err.Error()}
	}
	req.Header.Set("content-type", "application/json")
	req.Header.Set("x-api-key", apiKey)

	res, err := httpClient.Do(req)
	if err != nil {
		return nil, &CoworkkitError{Message: fmt.Sprintf("Coworkkit /session unreachable: %v — is the service deployed/reachable?", err)}
	}
	defer res.Body.Close()
	text, _ := io.ReadAll(res.Body)

	var body map[string]any
	ok := json.Unmarshal(text, &body) == nil // non-JSON (HTML) → ok=false, never a crash

	if res.StatusCode < 200 || res.StatusCode >= 300 || !ok {
		detail := "non-JSON response — is the service deployed/reachable?"
		reason := ""
		if ok {
			if e, isStr := body["error"].(string); isStr {
				detail = e
			}
			if r, isStr := body["reason"].(string); isStr {
				reason = r
			}
		}
		return nil, &CoworkkitError{
			Status:  res.StatusCode,
			Reason:  reason,
			Message: fmt.Sprintf("Coworkkit /session failed (HTTP %d): %s", res.StatusCode, detail),
		}
	}
	return body, nil // relay unchanged — the contract grows additively
}