client

package
v0.10.4 Latest Latest
Warning

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

 Go to latest Published: May 29, 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 IsNotFound 

func IsNotFound(err error) bool

IsNotFound returns true if the error is a 404 APIError.

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) 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) 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) 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) 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 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"`
	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
	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"`
}

LintDiagnostic is a single lint diagnostic

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 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.