papers/hanzo-sdk-ecosystem/sections/02-sdk-architecture.tex

\section{SDK Architecture}


\subsection{Design Principles}

\begin{enumerate}
    \item \textbf{Consistency}: Uniform patterns across languages where possible
    \item \textbf{Idiomaticity}: Respect language conventions and ecosystem norms
    \item \textbf{Minimal Dependencies}: Standard library preferred
    \item \textbf{Ergonomics}: Developer experience prioritized
\end{enumerate}

\subsection{SDK Components}

Each SDK provides:

\begin{itemize}
    \item \textbf{Client}: Configured HTTP client with authentication
    \item \textbf{Resources}: API resource classes (Products, Orders, etc.)
    \item \textbf{Models}: Request/response data structures
    \item \textbf{Errors}: Typed exception hierarchy
    \item \textbf{Utilities}: Pagination, webhook verification, etc.
\end{itemize}

\subsection{Resource Abstraction}

\begin{definition}[SDK Resource]
A resource $R$ exposes CRUD operations:
\begin{itemize}
    \item $list(params) \rightarrow Collection$
    \item $create(data) \rightarrow Instance$
    \item $retrieve(id) \rightarrow Instance$
    \item $update(id, data) \rightarrow Instance$
    \item $delete(id) \rightarrow void$
\end{itemize}
\end{definition}