eSlider
cff8145f8c
BREAKING:
- Binary renamed oo-cli → oo; install path is now
github.com/eslider/go-onlyoffice/cmd/oo.
- Former internal/cli tree removed; cobra commands live in cmd/oo/ as
package main, split by domain (calendar.go, crm.go, tasks.go, apps.go,
common.go, main.go).
- internal/applications moved to cmd/oo/applications/ (CV-specific workflow;
not a library feature).
- examples/applications removed (it depended on an internal package).
Library split (mechanical, zero API surface change):
- client.go — Client, Credentials, Defaults, env helpers, NewClient.
- request.go — Request, Query, Time, Token, MetaResponse, Permissions.
- auth.go — Authenticate/AuthenticateContext/InvalidateToken.
- http.go — transport + ResponseArray/ResponseObject/postFormObject/
putFormObject/deleteObject/unmarshalResponseObject (renamed
from httpx.go).
- projects.go, tasks.go, users.go, calendar.go, crm.go, files.go — typed
/ untyped domain methods. tasks_extra.go merged into tasks.go.
- onlyoffice.go deleted (content redistributed).
AGENTS.md, CHANGELOG.md, README.md updated accordingly.
Made-with: Cursor
3.4 KiB
3.4 KiB
AGENTS — go-onlyoffice
Canonical Go client for OnlyOffice Workspace (Projects + Calendar + CRM) and the oo command.
Topology
- Library — flat package
onlyofficeat repo root. Split by domain file, not by subpackage, so every call site readsc.XxxYyy()against a single*Client. Files:client.go—Client,Credentials,Defaults, env helpers,NewClient.request.go—Request,Query,Time,Token,MetaResponse,Permissions.auth.go—Authenticate,AuthenticateContext,InvalidateToken,Auth, token lifecycle.http.go— transport + DRY response decoders (ResponseArray/ResponseObject/postFormObject/putFormObject/deleteObject).projects.go,tasks.go,users.go,calendar.go,crm.go,files.go— typed / untyped domain methods.- Pure stdlib +
google/go-querystring; no UI, no dotenv.
- CLI —
cmd/oo/aspackage main. Cobra wrapper that loads.envviagodotenvat startup. Split by domain:main.go,common.go,calendar.go,tasks.go,crm.go,apps.go. CLI-only deps (spf13/cobra,joho/godotenv) stay out of the library. - Applications sync —
cmd/oo/applications/. README→CRM bridge, CV-specific; kept undercmd/oo/so it's clear it's internal to the binary, not a library feature.
Rules
- Library must never call
godotenv.Load()— the CLI does that. - New endpoints go into the library first; CLI commands are thin wrappers.
- Prefer
ResponseObject/postFormObject/putFormObject/deleteObjectover hand-rolledjson.Unmarshal(responseField(...))blocks — they exist for DRY, use them. - Domain split is by file, not by subpackage. Don't introduce
internal/orpkg/*subpackages inside the library — it flattens the*Clientcall surface for a reason. - No secrets in the repo; use
.env(gitignored). Commit.env.exampleonly. - Follow SemVer on tags; this repo is tagged at GitHub under
git@github.com:eSlider/go-onlyoffice.git.
Testing policy (2026-04-24)
No synthetic OnlyOffice mockups. Protocol-level behaviour must be
verified against a real OnlyOffice instance. httptest.NewServer is only
acceptable for testing the caller's logic that the library can't reach
(for example, the user's own HTTP handler). Anywhere we would otherwise
write mux.HandleFunc("/api/2.0/...") to emulate OnlyOffice, we write an
integration test instead.
- Unit tests (
*_test.go, no build tag) — pure Go: parsers, encoders, struct conversions. No network. No fake servers that emulate the vendor. - Integration tests (
//go:build integrationtag in*_integration_test.go) — hit a live OnlyOffice instance. Credentials come fromONLYOFFICE_URL,ONLYOFFICE_USER,ONLYOFFICE_PASS(aliases_HOST/_NAME/_PASSWORDalso accepted). Tests skip cleanly when credentials are missing sogo test ./...remains green in CI. - Run integration with:
go test -tags=integration ./.... - New endpoints must ship with an integration test before merge.
Related
eSlider/inventar— ASR/ADR (see ASR-0008 Go library module conventions).eSlider/inventar-sync— OnlyOffice → Gitea issue sync, consumes this library.produktor.io/vidarr— legacy consumer being migrated frompkg/onlyofficeto this module.