> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gavai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> Two TypeScript clients for gavAI — choose by surface and auth scheme.

export const PageMeta = ({audience, readingTime, prereqs, level}) => {
  const items = [audience && ({
    key: "audience",
    label: "AUDIENCE",
    value: audience
  }), readingTime && ({
    key: "time",
    label: "READ",
    value: readingTime
  }), level && ({
    key: "level",
    label: "LEVEL",
    value: level
  }), prereqs && prereqs.length > 0 && ({
    key: "prereqs",
    label: "PREREQS",
    value: prereqs.join(" · ")
  })].filter(Boolean);
  if (items.length === 0) return null;
  return <div className="gv-page-meta" role="group" aria-label="Page metadata">
      {items.map(item => <div className="gv-page-meta__item" key={item.key}>
          <span className="gv-page-meta__label">{item.label}</span>
          <span className="gv-page-meta__value">{item.value}</span>
        </div>)}
    </div>;
};

export const Path = ({icon, title, href, children}) => <a className="gv-choose-path__card" href={href}>
    {icon && <span className="gv-choose-path__icon" aria-hidden="true">
        <Icon icon={icon} />
      </span>}
    <h4 className="gv-choose-path__title">{title}</h4>
    {children && <p className="gv-choose-path__body">{children}</p>}
    <svg className="gv-choose-path__arrow" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <line x1="7" y1="17" x2="17" y2="7" />
      <polyline points="7 7 17 7 17 17" />
    </svg>
  </a>;

export const ChoosePath = ({eyebrow = "CHOOSE YOUR PATH", label, children}) => <section className="gv-choose-path">
    <div className="gv-choose-path__header">
      <Eyebrow label={eyebrow} />
      {label && <h3 className="gv-choose-path__label">{label}</h3>}
    </div>
    <div className="gv-choose-path__grid">{children}</div>
  </section>;

export const FeatureTable = ({columns, rows, featuredRow, caption, variant}) => <div className={`gv-feature-table ${variant ? `gv-feature-table--${variant}` : ""}`}>
    <table>
      {caption && <caption className="gv-feature-table__caption">{caption}</caption>}
      <thead>
        <tr>
          {columns.map(col => <th key={col.key} scope="col">
              <span className="gv-feature-table__header">{col.label}</span>
            </th>)}
        </tr>
      </thead>
      <tbody>
        {rows.map((row, i) => {
  const rowClass = [i === featuredRow ? "gv-feature-table__row--featured" : "", row.chosen ? "gv-feature-table__row--chosen" : ""].filter(Boolean).join(" ");
  return <tr key={i} className={rowClass}>
              {columns.map(col => {
    const v = row[col.key];
    if (variant === "tradeoff" && Array.isArray(v)) {
      const pill = col.key === "pros" ? "gv-feature-table__pill--pro" : col.key === "cons" ? "gv-feature-table__pill--con" : "";
      return <td key={col.key}>
                      {v.map((item, j) => <span key={j} className={`gv-feature-table__pill ${pill}`}>{item}</span>)}
                    </td>;
    }
    return <td key={col.key}>{v}</td>;
  })}
            </tr>;
})}
      </tbody>
    </table>
  </div>;

export const BrandCard = ({eyebrow, title, href, icon, badge, cta, featured = false, horizontal = false, children}) => {
  const classes = ["gv-card", featured && "gv-card--featured", horizontal && "gv-card--horizontal"].filter(Boolean).join(" ");
  const inner = <>
      {icon && <span className="gv-card__icon" aria-hidden="true">
          <Icon icon={icon} />
        </span>}
      <div className="gv-card__main">
        {(eyebrow || badge) && <div className="gv-card__meta">
            {eyebrow && <Eyebrow label={eyebrow} tone="muted" />}
            {badge && <span className="gv-card__badge">{badge}</span>}
          </div>}
        <h3 className="gv-card__title">{title}</h3>
        {children && <div className="gv-card__body">{children}</div>}
        {cta && <span className="gv-card__cta">
            {cta}
            <svg className="gv-card__cta-arrow" viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
              <line x1="7" y1="17" x2="17" y2="7" />
              <polyline points="7 7 17 7 17 17" />
            </svg>
          </span>}
      </div>
    </>;
  return href ? <a className={classes} href={href}>
      {inner}
    </a> : <div className={classes}>{inner}</div>;
};

export const Eyebrow = ({label, tone = "default"}) => <div className={`gv-eyebrow gv-eyebrow--${tone}`}>
    <span className="gv-eyebrow__bar" aria-hidden="true" />
    <span className="gv-eyebrow__label">{label}</span>
  </div>;

<Eyebrow label="SDKs" />

<PageMeta audience="Developers" readingTime="3 min" prereqs={["Bun or Node 18+"]} level="Beginner" />

gavAI ships two TypeScript packages on npm. They target different API surfaces and different auth schemes. By the end of this page you will know which one to install and where its full documentation lives.

<ChoosePath label="Pick the SDK that matches your surface">
  <Path icon="zap" title="I'm building a product or backend" href="/sdks/typescript-sdk">
    Use `@gavai/sdk` — bearer-token auth, full public REST API coverage.
  </Path>

  <Path icon="server" title="I'm working on platform / admin tooling" href="/sdks/typescript-low-level">
    Use `@gavai/sdk-typescript` — signed control-plane client. Rarely the right choice for product code.
  </Path>
</ChoosePath>

## Pick one

<FeatureTable
  columns={[
{ key: "package", label: "Package" },
{ key: "surface", label: "API surface" },
{ key: "auth", label: "Auth" }
]}
  rows={[
{
  package: "`@gavai/sdk`",
  surface: "Public REST API — `https://api.gavai.app/v1`",
  auth: "Bearer token (`gak_live_*`, `gak_test_*`, or `gst_*`)"
},
{
  package: "`@gavai/sdk-typescript`",
  surface: "Signed admin / control-plane — `/api/v1`",
  auth: "Mutual HMAC-SHA256 (`gavai_<env>_<keyid>_<secret>`)"
}
]}
/>

If you are integrating against the public API — building a backend service, a CLI, a CI job, a customer-facing app — install `@gavai/sdk`. The low-level package exists for platform tooling and is rarely the right choice for product code.

<Columns cols={2}>
  <BrandCard eyebrow="SDK" title="@gavai/sdk" href="/sdks/typescript-sdk">
    High-level typed client. Covers all 14 public API resources. Bearer-token auth. Start here.
  </BrandCard>

  <BrandCard eyebrow="SDK" title="@gavai/sdk-typescript" href="/sdks/typescript-low-level">
    Low-level signed client for platform admin work. Mutual HMAC signing on every request.
  </BrandCard>
</Columns>

## Other languages

<Note>
  TypeScript and JavaScript only today. Python, Go, and Rust clients are on the roadmap. Until they ship, call the REST API directly — see the [API reference](/api-reference/introduction).
</Note>

## Next steps

<Columns cols={2}>
  <BrandCard title="Your first integration" href="/guides/first-integration">
    Install `@gavai/sdk`, authenticate, patch a page, and publish — in under 10 minutes.
  </BrandCard>

  <BrandCard title="Error handling" href="/sdks/error-handling">
    Typed error classes, retry-safe patterns, and what to log when something fails.
  </BrandCard>
</Columns>