client

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DetectContentType added in v0.10.0 

func DetectContentType(filePath string) string

DetectContentType returns the MIME type the CLI sends for a local file.

func ExtractSpreadsheetID added in v0.14.0 

func ExtractSpreadsheetID(gsURL string) string

ExtractSpreadsheetID extracts the spreadsheet ID from a gs://SHEET_ID URL.

func IsGoogleSheetsURL added in v0.14.0 

func IsGoogleSheetsURL(path string) bool

IsGoogleSheetsURL returns true if the path looks like a Google Sheets URL. Supported formats:

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound returns true if the error is a 404 APIError.

func NormalizeGoogleSheetsURL added in v0.14.0 

func NormalizeGoogleSheetsURL(path string) string

NormalizeGoogleSheetsURL converts various Google Sheets URL formats to gs://SHEET_ID.

Types

type APIError 

type APIError struct {
	StatusCode int
	Code       string
	Message    string
	RetryAfter string
}

APIError is a typed error returned by API calls, with the HTTP status code.

func (*APIError) Error 

func (e *APIError) Error() string

type CacheEntry 

type CacheEntry struct {
	FileID      string `json:"file_id"`
	RevisionID  string `json:"revision_id"`
	ContentHash string `json:"content_hash"`
	Bytes       int64  `json:"bytes"`
	Filename    string `json:"filename"`
}

CacheEntry records the server-side identity for a local file path, plus the content hash at the time the entry was last updated.

type CalcResponse 

type CalcResponse struct {
	Touched    map[string]CalcTouchedCell `json:"touched"`
	Changed    []string                   `json:"changed,omitempty"` // cells whose computed value changed
	Errors     []CellError                `json:"errors"`
	File       *string                    `json:"file,omitempty"`        // base64, stateless only
	RevisionID *string                    `json:"revision_id,omitempty"` // new revision, files-backed only
}

CalcResponse is the response from the calc endpoint

type CalcTouchedCell 

type CalcTouchedCell struct {
	Value   string  `json:"value"`
	Formula *string `json:"formula"`
}

CalcTouchedCell is a cell that was recalculated

type CellError 

type CellError struct {
	Address string  `json:"address"`
	Code    string  `json:"code"`
	Formula *string `json:"formula"`
	Detail  *string `json:"detail"`
}

CellError is a formula calculation error

type Client 

type Client struct {
	BaseURL    string
	APIKey     string
	OrgID      string
	UserAgent  string
	HTTPClient *http.Client
	Stateless  bool // when true, use POST-file-in-body endpoints only
	// contains filtered or unexported fields
}

Client is a Witan API client

func New 

func New(baseURL, apiKey, orgID string, stateless bool) *Client

New creates a new Witan API client. By default it uses the /v0/files endpoints with a local hash cache for deduplication. Pass stateless=true to use POST-file-in-body endpoints instead (zero data retention).

func (*Client) Calc 

func (c *Client) Calc(filePath string, params url.Values) (*CalcResponse, error)

Calc recalculates formulas via POST /v0/xlsx/calc and returns results

func (*Client) CreateGoogleSheet added in v0.14.0 

func (c *Client) CreateGoogleSheet(title string) (*CreateGoogleSheetResponse, error)

CreateGoogleSheet creates a new Google Sheet in the user's Google Drive. Endpoint: POST /v0/orgs/:org_id/gsheets

func (*Client) DownloadFileContent 

func (c *Client) DownloadFileContent(fileId, revisionId string) ([]byte, error)

DownloadFileContent calls GET /v0/files/:fileId/content and returns the raw file bytes.

func (*Client) EnsureUploaded 

func (c *Client) EnsureUploaded(filePath string) (fileId, revisionId string, err error)

EnsureUploaded looks up the file by path in the cache and returns (fileId, revisionId). If the cached entry's content hash matches the current file, the cached pair is returned. If the file has changed, a new revision is PUT under the same fileID; if that PUT fails because the fileID is gone (or the server rejects the version), it falls back to a fresh POST. With no cache entry, a fresh POST is made.

On a 404 from a downstream op, the caller should call ReuploadFile, which evicts and runs through this path again.

func (*Client) Exec 

func (c *Client) Exec(filePath string, req ExecRequest, save bool) (*ExecResponse, error)

Exec runs JavaScript against a workbook via multipart POST /v0/xlsx/exec.

func (*Client) ExecCreate added in v0.7.0 

func (c *Client) ExecCreate(filePath string, req ExecRequest, save bool) (*ExecResponse, error)

ExecCreate runs JavaScript against a new workbook via multipart POST /v0/xlsx/exec?create=true.

func (*Client) FilesCalc 

func (c *Client) FilesCalc(fileId, revisionId string, params url.Values) (*CalcResponse, error)

FilesCalc calls GET /v0/files/:fileId/xlsx/calc and returns calc results.

func (*Client) FilesExec 

func (c *Client) FilesExec(fileID, revisionID string, req ExecRequest, save bool) (*ExecResponse, error)

FilesExec calls POST /v0/files/:fileId/xlsx/exec with JSON body and returns exec results.

func (*Client) FilesLint 

func (c *Client) FilesLint(fileId, revisionId string, params url.Values) (*LintResponse, error)

FilesLint calls GET /v0/files/:fileId/xlsx/lint and returns lint diagnostics.

func (*Client) FilesPPTXExec added in v0.11.0 

func (c *Client) FilesPPTXExec(fileID, revisionID string, req ExecRequest, save bool) (*ExecResponse, error)

FilesPPTXExec calls POST /v0/files/:fileId/pptx/exec with a JSON body.

func (*Client) FilesPPTXLint added in v0.14.0 

func (c *Client) FilesPPTXLint(fileID, revisionID string, params url.Values) (*PptxLintResponse, error)

FilesPPTXLint calls GET /v0/files/:fileId/pptx/lint.

func (*Client) FilesPPTXRender added in v0.11.0 

func (c *Client) FilesPPTXRender(fileID, revisionID string, params map[string]string) ([]byte, string, error)

FilesPPTXRender calls GET /v0/files/:fileId/pptx/render and returns image bytes.

func (*Client) FilesRead added in v0.3.1 

func (c *Client) FilesRead(fileId, revisionId string, params url.Values) (*ReadResponse, error)

FilesRead calls GET /v0/files/:fileId/read.

func (*Client) FilesReadOutline added in v0.3.1 

func (c *Client) FilesReadOutline(fileId, revisionId string, params url.Values) (*ReadOutlineResponse, error)

FilesReadOutline calls GET /v0/files/:fileId/read?outline=true.

func (*Client) FilesRender 

func (c *Client) FilesRender(fileId, revisionId string, params map[string]string) ([]byte, string, error)

FilesRender calls GET /v0/files/:fileId/xlsx/render and returns image bytes.

func (*Client) FilesXlsxRPCWebSocketURL added in v0.10.0 

func (c *Client) FilesXlsxRPCWebSocketURL(fileID, revisionID, hint, locale string) (string, error)

FilesXlsxRPCWebSocketURL builds the files-backed xlsx RPC WebSocket URL.

func (*Client) GSheetsExec added in v0.14.0 

func (c *Client) GSheetsExec(spreadsheetID string, req ExecRequest) (*ExecResponse, error)

GSheetsExec executes JavaScript against a Google Sheets spreadsheet. Endpoint: POST /v0/orgs/:org_id/gsheets/:spreadsheet_id/exec

func (*Client) GSheetsExecCreate added in v0.14.0 

func (c *Client) GSheetsExecCreate(req ExecRequest) (*ExecResponse, error)

GSheetsExecCreate creates a new Google Sheet and executes JavaScript against it. Endpoint: POST /v0/orgs/:org_id/gsheets/new/exec

func (*Client) GSheetsLint added in v0.14.0 

func (c *Client) GSheetsLint(spreadsheetID string, params url.Values) (*LintResponse, error)

GSheetsLint runs lint diagnostics on a Google Sheets spreadsheet. Endpoint: GET /v0/orgs/:org_id/gsheets/:spreadsheet_id/lint

func (*Client) GSheetsRPCWebSocketURL added in v0.14.0 

func (c *Client) GSheetsRPCWebSocketURL() (string, error)

GSheetsRPCWebSocketURL returns the WebSocket URL for Google Sheets RPC. Endpoint: GET /v0/orgs/:org_id/gsheets/ws Spreadsheet binding happens in the init message (spreadsheet_id or create: true).

func (*Client) GSheetsRender added in v0.14.0 

func (c *Client) GSheetsRender(spreadsheetID string, params map[string]string) ([]byte, string, error)

GSheetsRender renders a range of a Google Sheets spreadsheet as an image. Endpoint: GET /v0/orgs/:org_id/gsheets/:spreadsheet_id/render

func (*Client) Lint 

func (c *Client) Lint(filePath string, params url.Values) (*LintResponse, error)

Lint runs lint on a file via POST /v0/xlsx/lint and returns diagnostics

func (*Client) PPTXExec added in v0.11.0 

func (c *Client) PPTXExec(filePath string, req ExecRequest, save bool) (*ExecResponse, error)

PPTXExec runs Office.js-compatible JavaScript against a PPTX file via multipart POST /v0/pptx/exec.

func (*Client) PPTXExecCreate added in v0.11.0 

func (c *Client) PPTXExecCreate(filePath string, req ExecRequest, save bool) (*ExecResponse, error)

PPTXExecCreate runs Office.js-compatible JavaScript against a new empty PPTX file via multipart POST /v0/pptx/exec?create=true.

func (*Client) PPTXExecTypes added in v0.14.0 

func (c *Client) PPTXExecTypes() ([]byte, error)

PPTXExecTypes fetches the combined TypeScript declarations for the pptx exec sandbox (stripped Office.js surface plus Witan chart extensions) via GET /v0/pptx/exec/types. The endpoint is public and returns raw text/plain; no auth headers are required.

func (*Client) PPTXLint added in v0.14.0 

func (c *Client) PPTXLint(filePath string, params url.Values) (*PptxLintResponse, error)

PPTXLint lints a PPTX file via POST /v0/pptx/lint.

func (*Client) PPTXRender added in v0.11.0 

func (c *Client) PPTXRender(filePath string, params map[string]string) ([]byte, string, error)

PPTXRender renders a PPTX slide and returns the image bytes.

func (*Client) Read added in v0.3.1 

func (c *Client) Read(filePath string, params url.Values) (*ReadResponse, error)

Read calls POST /v0/read with a file in the body.

func (*Client) ReadOutline added in v0.3.1 

func (c *Client) ReadOutline(filePath string, params url.Values) (*ReadOutlineResponse, error)

ReadOutline calls POST /v0/read?outline=true with a file in the body.

func (*Client) Render 

func (c *Client) Render(filePath string, params map[string]string) ([]byte, string, error)

Render renders a region of a spreadsheet and returns the image bytes

func (*Client) ReuploadFile 

func (c *Client) ReuploadFile(filePath string) (fileId, revisionId string, err error)

ReuploadFile evicts the cache entry for the given file and re-uploads it. Use this after getting a 404 from a files endpoint (stale cache entry).

func (*Client) StatelessXlsxRPCWebSocketURL added in v0.10.0 

func (c *Client) StatelessXlsxRPCWebSocketURL() (string, error)

StatelessXlsxRPCWebSocketURL builds the stateless xlsx RPC WebSocket URL.

func (*Client) UpdateCachedRevision 

func (c *Client) UpdateCachedRevision(filePath, fileID, revisionID string) error

UpdateCachedRevision updates the cache entry after a command produces a new revision for the given file path.

func (*Client) UploadFile 

func (c *Client) UploadFile(filePath string) (*FileResponse, error)

UploadFile uploads a local file via multipart POST to /v0/files and returns the file metadata including fileId and revisionId.

func (*Client) UploadFileVersion 

func (c *Client) UploadFileVersion(fileID, filePath string) (*FileResponse, error)

UploadFileVersion uploads a local file as a new revision of an existing file.

type CreateGoogleSheetRequest added in v0.14.0 

type CreateGoogleSheetRequest struct {
	Title string `json:"title,omitempty"`
}

CreateGoogleSheetRequest is the request body for creating a new Google Sheet.

type CreateGoogleSheetResponse added in v0.14.0 

type CreateGoogleSheetResponse struct {
	SpreadsheetID string `json:"spreadsheet_id"`
	Title         string `json:"title"`
	URL           string `json:"url"`
}

CreateGoogleSheetResponse is the response from creating a new Google Sheet.

type ErrorResponse 

type ErrorResponse struct {
	Error struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

ErrorResponse is the standard API error shape

type ExecAccess 

type ExecAccess struct {
	Operation string `json:"operation"` // read|write
	Address   string `json:"address"`
}

ExecAccess describes a workbook access observed during execution.

type ExecError 

type ExecError struct {
	Type    string `json:"type"` // syntax|runtime|timeout
	Code    string `json:"code"` // EXEC_SYNTAX_ERROR|EXEC_RUNTIME_ERROR|EXEC_TIMEOUT|EXEC_RESULT_TOO_LARGE
	Message string `json:"message"`
}

ExecError describes a script execution error.

type ExecRequest 

type ExecRequest struct {
	Code           string `json:"code"`
	Input          any    `json:"input,omitempty"`
	Filename       string `json:"filename,omitempty"`
	Title          string `json:"title,omitempty"` // Google Sheets create+exec only
	Locale         string `json:"locale,omitempty"`
	TimeoutMS      int    `json:"timeout_ms,omitempty"`
	MaxOutputChars int    `json:"max_output_chars,omitempty"`
}

ExecRequest is the request body for exec endpoints.

type ExecResponse 

type ExecResponse struct {
	Ok             bool            `json:"ok"`
	Stdout         string          `json:"stdout"`
	Truncated      bool            `json:"truncated,omitempty"`
	Result         json.RawMessage `json:"result,omitempty"`
	Images         []string        `json:"images,omitempty"`
	WritesDetected bool            `json:"writes_detected,omitempty"`
	Accesses       []ExecAccess    `json:"accesses,omitempty"`
	File           *string         `json:"file,omitempty"`        // base64, stateless save=true only
	RevisionID     *string         `json:"revision_id,omitempty"` // new revision, files-backed save=true only
	SpreadsheetID  string          `json:"spreadsheet_id,omitempty"`
	URL            string          `json:"url,omitempty"`
	Error          *ExecError      `json:"error,omitempty"`
}

ExecResponse is the response from exec endpoints.

type FileCache 

type FileCache struct {
	// contains filtered or unexported fields
}

FileCache persists path→(fileID, revision, contentHash) mappings on disk. If no writable directory is found, it operates in-memory only.

func NewFileCache 

func NewFileCache() *FileCache

NewFileCache probes for a writable cache directory using the cascade:

  1. $TMPDIR/witan/ (or os.TempDir()/witan/)
  2. .witan/ in cwd
  3. in-memory only (no persistence)

func (*FileCache) Evict 

func (fc *FileCache) Evict(filePath, baseURL, orgID string)

Evict removes a cache entry by local file identity.

func (*FileCache) Get 

func (fc *FileCache) Get(filePath, baseURL, orgID string) (CacheEntry, bool)

Get looks up a cache entry by local file identity.

func (*FileCache) Put 

func (fc *FileCache) Put(filePath, baseURL, orgID string, entry CacheEntry)

Put stores a cache entry by local file identity.

type FileResponse 

type FileResponse struct {
	ID         string `json:"id"`
	Object     string `json:"object"`
	Filename   string `json:"filename"`
	Bytes      int64  `json:"bytes"`
	RevisionID string `json:"revision_id"`
	Status     string `json:"status"`
}

FileResponse is the response from POST /v0/files.

type LintDiagnostic 

type LintDiagnostic struct {
	Severity string                `json:"severity"`
	RuleId   string                `json:"ruleId"`
	Message  string                `json:"message"`
	Location *string               `json:"location"`
	Object   *LintDiagnosticObject `json:"object,omitempty"`
}

LintDiagnostic is a single lint diagnostic

type LintDiagnosticObject added in v0.14.0 

type LintDiagnosticObject struct {
	// Kind is one of the known object kinds: "chart", "image", "shape", "object"
	Kind string  `json:"kind"`
	Name *string `json:"name"`
}

LintDiagnosticObject references the floating object (chart, image, shape) a diagnostic is about

type LintResponse 

type LintResponse struct {
	Diagnostics []LintDiagnostic `json:"diagnostics"`
	Total       int              `json:"total"`
}

LintResponse is the response from the lint endpoint

type OutlineEntry added in v0.3.1 

type OutlineEntry struct {
	Title  string `json:"title"`
	Level  int    `json:"level"`
	Pages  string `json:"pages,omitempty"`
	Slides string `json:"slides,omitempty"`
	Offset *int   `json:"offset,omitempty"`
}

OutlineEntry is a single entry in a document outline.

type PersistentCookieJar added in v0.10.0 

type PersistentCookieJar struct {
	// contains filtered or unexported fields
}

PersistentCookieJar persists HTTP cookies to disk for API affinity.

func NewPersistentCookieJar added in v0.10.0 

func NewPersistentCookieJar(path string) (*PersistentCookieJar, error)

func (*PersistentCookieJar) Cookies added in v0.10.0 

func (pj *PersistentCookieJar) Cookies(u *url.URL) []*http.Cookie

func (*PersistentCookieJar) SetCookies added in v0.10.0 

func (pj *PersistentCookieJar) SetCookies(u *url.URL, cookies []*http.Cookie)

type PptxLintDiagnostic added in v0.14.0 

type PptxLintDiagnostic struct {
	Severity    string  `json:"severity"`
	RuleId      string  `json:"ruleId"`
	Message     string  `json:"message"`
	Location    *string `json:"location"`
	SlideNumber *int    `json:"slideNumber"`
	SlideId     *string `json:"slideId"`
	ShapeId     *string `json:"shapeId"`
	ShapeName   *string `json:"shapeName"`
}

PptxLintDiagnostic is a single PPTX lint diagnostic

type PptxLintResponse added in v0.14.0 

type PptxLintResponse struct {
	Diagnostics []PptxLintDiagnostic `json:"diagnostics"`
	Total       int                  `json:"total"`
}

PptxLintResponse is the response from the PPTX lint endpoint

type ReadMetadata added in v0.3.1 

type ReadMetadata struct {
	TotalPages  *int `json:"total_pages,omitempty"`
	ReadPages   *int `json:"read_pages,omitempty"`
	TotalSlides *int `json:"total_slides,omitempty"`
	ReadSlides  *int `json:"read_slides,omitempty"`
	TotalLines  int  `json:"total_lines"`
	Offset      int  `json:"offset"`
	Limit       int  `json:"limit"`
}

ReadMetadata holds pagination and dimension metadata for read responses.

type ReadOutlineMetadata added in v0.3.1 

type ReadOutlineMetadata struct {
	TotalPages  *int `json:"total_pages,omitempty"`
	TotalSlides *int `json:"total_slides,omitempty"`
	TotalLines  *int `json:"total_lines,omitempty"`
}

ReadOutlineMetadata holds dimension metadata for outline responses.

type ReadOutlineResponse added in v0.3.1 

type ReadOutlineResponse struct {
	Outline  []OutlineEntry      `json:"outline"`
	Metadata ReadOutlineMetadata `json:"metadata"`
}

ReadOutlineResponse is the response from the read endpoint (outline mode).

type ReadResponse added in v0.3.1 

type ReadResponse struct {
	Content  string       `json:"content"`
	Format   string       `json:"format"`
	Metadata ReadMetadata `json:"metadata"`
}

ReadResponse is the response from the read endpoint (content mode).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.