From 490426c2779160f1a9b168f6ccae9dd8dccf89e9 Mon Sep 17 00:00:00 2001 From: Andriy Oblivantsev Date: Thu, 6 Aug 2026 14:26:43 +0100 Subject: [PATCH] docs(crm): capture association graph and invoice/mail quirks Document Medex-learned OO rules (one company, entityId at create, PDF cache/cleanup, Matrix # truncation) and add invoices pdf/status helpers. --- AGENTS.md | 2 +- CHANGELOG.md | 12 +++ README.md | 37 +++++++-- cmd/oo/invoices.go | 143 +++++++++++++++++++++++++++++++++-- cmd/oo/mails.go | 2 +- cmd/oo/main.go | 8 +- docs/crm-associations.md | 120 +++++++++++++++++++++++++++++ invoices.go | 158 +++++++++++++++++++++++++++++++++++++++ mails.go | 9 --- 9 files changed, 465 insertions(+), 26 deletions(-) create mode 100644 docs/crm-associations.md diff --git a/AGENTS.md b/AGENTS.md index bfbbce5..ee5051e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ Canonical Go client for OnlyOffice Workspace (Projects + Calendar + CRM) and the - `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`, `mails.go` — typed / untyped domain methods. **`files.go`** — CRM opportunity upload plus **project/task Documents** (`GetProjectFiles`, `UploadProjectFile`, `GetTaskFiles`, `AttachFilesToTask`, `UploadTaskFile`, `DetachTaskFile`, `GetFile`, `RenameFile`, `DeleteFiles`, `DownloadFile`). **`mails.go`** — OnlyOffice Workspace Mail addon (`ListMailAccounts`, `ListMailFolders`, `ListMailMessages`, `GetMailMessage`, `RemoveMailMessages`). + - `projects.go`, `tasks.go`, `users.go`, `calendar.go`, `crm.go`, `files.go`, `mails.go`, `invoices.go` — typed / untyped domain methods. **`files.go`** — CRM opportunity upload plus **project/task Documents**. **`mails.go`** — OnlyOffice Workspace Mail. **`invoices.go`** — CRM invoices, PDF regen/cleanup, status. Association rules: [`docs/crm-associations.md`](docs/crm-associations.md). - Pure stdlib + `google/go-querystring`; no UI, no dotenv. - **CLI — `cmd/oo/` as `package main`.** Cobra wrapper that loads `.env` via `godotenv` at startup. **Subject-based command tree** mirroring [`tea`](https://gitea.com/gitea/tea): - `main.go` — entry point (docstring lists the command tree). diff --git a/CHANGELOG.md b/CHANGELOG.md index a399d00..6d83a24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,18 @@ All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## Unreleased + +### Added + +* **docs:** CRM association graph and OO quirks (`docs/crm-associations.md`) +* **crm:** `ForceRegenerateInvoicePDF`, `SetInvoiceStatus`, `PurgeStaleInvoicePDFs`, contact/opportunity file list helpers +* **oo:** `invoices pdf`, `pdf-cleanup`, `status`; create `--consignee`; draft-invoice force-regens PDF + +### Fixed + +* Document that invoice→deal must be set at create (`update --opportunity` often HTTP 400) + ## [0.9.0](https://github.com/eSlider/go-onlyoffice/compare/v0.8.3...v0.9.0) (2026-07-26) diff --git a/README.md b/README.md index 3fab0de..bcfd1ae 100644 --- a/README.md +++ b/README.md @@ -623,13 +623,11 @@ oo tasks files detach 208 12345 | `projects` | `list`, `get`, `milestones`, `create`, `update`, `delete`, **`files`** (`list`, `upload`, `download`, `rename`, `delete`) | | `tasks` | `list`, `get`, `create`, `update`, `delete`, `subtask add`, **`files`** (`list`, `upload`, `detach`) | | `users` | `list`, `self` (alias: `oo whoami`) | -| `contacts` | `list`, `get`, `delete`, `info-add` | -| `persons` | `list` (filtered), `create`, `delete` | -| `companies` | `list` (filtered), `create`, `delete` | -| `contacts` | `list`, `get`, `delete`, `info-add`, `dedupe-info` | +| `contacts` | `list`, `get`, `delete`, `info-add`, `merge`, `dedupe-info` | | `persons` | `list`, `create`, `delete`, `dedupe` | | `companies` | `list`, `create`, `delete`, `dedupe`, `dedupe-persons` | | `opportunities` | `list`, `get`, `create`, `delete`, `stages`, `member-add`, `dedupe`, `dedupe-members`, `fix-titles` | +| `invoices` | `list`, `get`, `create`, `update`, `pdf`, `pdf-cleanup`, `status`, `delete`, `items …` | | `crm` | `cleanup` | | `mails` | `accounts`, `folders`, `list`, `get`, `draft`, `attach`, `draft-invoice`, `delete` | | `cases` | `list`, `create`, `delete`, `member-add` | @@ -718,6 +716,32 @@ oo opportunities dedupe-members oo opportunities fix-titles ``` +Merge two known company ids (keeps `INTO`): + +```bash +oo contacts merge FROM_ID INTO_ID +``` + +Company ↔ person ↔ deal ↔ project ↔ invoice ↔ mail rules and OO quirks: +[docs/crm-associations.md](docs/crm-associations.md). + +### Invoices (`oo invoices`) + +**Problem:** Bill a client deal as Draft, regenerate PDF, prune duplicate PDF +attachments, prepare OnlyOffice Mail — without inventing a second bill-to company. + +```bash +# Always pass --opportunity at create (update --opportunity often HTTP 400) +oo invoices create --number INV-2026-01 --contact COMPANY_ID --item ITEM_ID \ + --price 300 --opportunity DEAL_ID --language de-DE \ + --line-description "…" --terms $'…' --description $'…' --po "Deal #DEAL_ID" + +oo invoices pdf 41 --force +oo invoices pdf-cleanup INVOICE_ID +oo invoices status INVOICE_ID --status draft +oo mails draft-invoice --invoice INVOICE_ID --to info@client.de +``` + **Deal grouping flag** — when the same role at the same company created separate deals (`Engineer @ Acme` vs `Engineer`): @@ -829,10 +853,13 @@ oo mails draft --to client@example.com --subject "Rechnung INV-2026-01" \ # Attach an OnlyOffice Files document (e.g. invoice PDF file id) to a draft oo mails attach 7301 --file-id 12345 -# Regenerate invoice PDF + draft + attach (does not send) +# Regenerate invoice PDF (force) + draft + attach (does not send) oo mails draft-invoice --invoice 16 --to info@example.com ``` +Matrix / chat URLs in signatures: use plain text +`chat: https://matrix.to/#/@user:server` — HTML `` truncates at `#`. + **Table output** splits the `from` header into `fromName` and `fromAddress` (e.g. `Bitfinex` + `no-reply@bitfinex.com`). **JSON output** returns the raw API payload. diff --git a/cmd/oo/invoices.go b/cmd/oo/invoices.go index 8046fab..da6555c 100644 --- a/cmd/oo/invoices.go +++ b/cmd/oo/invoices.go @@ -21,6 +21,9 @@ func init() { invoicesCmd.AddCommand(invoiceGetCmd()) invoicesCmd.AddCommand(invoiceCreateCmd()) invoicesCmd.AddCommand(invoiceUpdateCmd()) + invoicesCmd.AddCommand(invoicePDFCmd()) + invoicesCmd.AddCommand(invoicePDFCleanupCmd()) + invoicesCmd.AddCommand(invoiceStatusCmd()) invoicesCmd.AddCommand(invoiceDeleteCmd()) invoicesCmd.AddCommand(invoiceItemsCmd()) } @@ -78,7 +81,7 @@ func invoiceGetCmd() *cobra.Command { func invoiceCreateCmd() *cobra.Command { var ( number, issueDate, dueDate, language, currency, terms, description, po string - contactID, itemID, opportunityID int64 + contactID, consigneeID, itemID, opportunityID int64 price, qty float64 lineDesc string ) @@ -87,8 +90,11 @@ func invoiceCreateCmd() *cobra.Command { Short: "Create a draft invoice with one line", Long: `Create a CRM invoice (Draft) with a single line. +Always pass --opportunity when a deal exists (entity link at create). Updating +--opportunity later often fails with HTTP 400 — see docs/crm-associations.md. + Example: - oo invoices create --number INV-2026-01 --contact 123 --item 10 \ + oo invoices create --number INV-2026-01 --contact CONTACT_ID --item 12 \ --price 300 --opportunity OPPORTUNITY_ID --line-description "Service package" \ --terms "…payment terms…" `, @@ -118,6 +124,7 @@ Example: IssueDate: issueDate, DueDate: dueDate, ContactID: contactID, + ConsigneeID: consigneeID, EntityID: opportunityID, EntityType: 0, // Opportunity Language: language, @@ -142,8 +149,9 @@ Example: }, } cmd.Flags().StringVar(&number, "number", "", "invoice number (e.g. INV-2026-01)") - cmd.Flags().Int64Var(&contactID, "contact", 0, "bill-to contact id (company preferred)") - cmd.Flags().Int64Var(&opportunityID, "opportunity", 0, "link to CRM opportunity/deal id") + cmd.Flags().Int64Var(&contactID, "contact", 0, "bill-to company contact id (canonical company, not a PDF-only clone)") + cmd.Flags().Int64Var(&consigneeID, "consignee", 0, "optional Empfänger person/contact id") + cmd.Flags().Int64Var(&opportunityID, "opportunity", 0, "link to CRM opportunity/deal id (set at create)") cmd.Flags().Int64Var(&itemID, "item", 0, "catalog invoice item id") cmd.Flags().Float64Var(&price, "price", 0, "line price") cmd.Flags().Float64Var(&qty, "qty", 1, "line quantity") @@ -163,8 +171,13 @@ func invoiceUpdateCmd() *cobra.Command { var description, po, terms string cmd := &cobra.Command{ Use: "update INVOICE_ID", - Short: "Update invoice (opportunity link, notes, PO, terms)", - Args: cobra.ExactArgs(1), + Short: "Update invoice (notes, PO, terms; opportunity link unreliable)", + Long: `Update Draft invoice fields. + +--opportunity often returns HTTP 400 on existing invoices. Prefer +oo invoices create … --opportunity, or delete+recreate. See docs/crm-associations.md. +`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { if opportunityID == 0 && !cmd.Flags().Changed("description") && !cmd.Flags().Changed("po") && !cmd.Flags().Changed("terms") { return fmt.Errorf("set --opportunity and/or --description and/or --po and/or --terms") @@ -190,13 +203,129 @@ func invoiceUpdateCmd() *cobra.Command { return nil }, } - cmd.Flags().Int64Var(&opportunityID, "opportunity", 0, "CRM opportunity/deal id to link") + cmd.Flags().Int64Var(&opportunityID, "opportunity", 0, "CRM opportunity/deal id (may 400 — prefer create)") cmd.Flags().StringVar(&description, "description", "", "invoice notes (Notizen); use \\n for line breaks") cmd.Flags().StringVar(&po, "po", "", "purchase order number") cmd.Flags().StringVar(&terms, "terms", "", "payment terms / footer (Bedingungen)") return cmd } +func invoicePDFCmd() *cobra.Command { + var force bool + cmd := &cobra.Command{ + Use: "pdf INVOICE_ID", + Short: "Return / regenerate invoice PDF file metadata", + Long: `GET /api/2.0/crm/invoice/{id}/pdf. + +With --force, touches the Draft to clear cached fileID first (layout changes). +`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + c, err := newOO(cmd) + if err != nil { + return err + } + var out map[string]any + if force { + out, err = c.ForceRegenerateInvoicePDF(cmd.Context(), args[0]) + } else { + out, err = c.InvoicePDFFile(cmd.Context(), args[0]) + } + if err != nil { + return err + } + printObject(out) + return nil + }, + } + cmd.Flags().BoolVar(&force, "force", false, "clear PDF cache then regenerate") + return cmd +} + +func invoicePDFCleanupCmd() *cobra.Command { + return &cobra.Command{ + Use: "pdf-cleanup INVOICE_ID", + Short: "Delete older P-*.pdf copies on company/deal; keep invoice.fileID", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + c, err := newOO(cmd) + if err != nil { + return err + } + deleted, err := c.PurgeStaleInvoicePDFs(cmd.Context(), args[0]) + if err != nil { + return err + } + if outputFormat == "json" { + printObject(map[string]any{"deleted": deleted}) + return nil + } + fmt.Printf("deleted %d stale PDF file(s): %v\n", len(deleted), deleted) + return nil + }, + } +} + +func invoiceStatusCmd() *cobra.Command { + var status string + cmd := &cobra.Command{ + Use: "status INVOICE_ID [INVOICE_ID...]", + Short: "Set invoice status (draft|billed|rejected|paid)", + Long: `PUT /api/2.0/crm/invoice/status/{id}. + +Billed invoices are not content-editable. Billed→Draft often does not work — +recreate as Draft instead (docs/crm-associations.md). +`, + Args: cobra.MinimumNArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + statusID, err := parseInvoiceStatus(status) + if err != nil { + return err + } + ids := make([]int64, 0, len(args)) + for _, a := range args { + var id int64 + if _, err := fmt.Sscan(a, &id); err != nil || id <= 0 { + return fmt.Errorf("invalid invoice id %q", a) + } + ids = append(ids, id) + } + c, err := newOO(cmd) + if err != nil { + return err + } + out, err := c.SetInvoiceStatus(cmd.Context(), statusID, ids...) + if err != nil { + return err + } + printObject(out) + return nil + }, + } + cmd.Flags().StringVar(&status, "status", "draft", "draft|billed|rejected|paid or numeric id") + return cmd +} + +func parseInvoiceStatus(s string) (int, error) { + s = strings.TrimSpace(strings.ToLower(s)) + switch s { + case "", "draft", "1": + return onlyoffice.InvoiceStatusDraft, nil + case "billed", "2": + return onlyoffice.InvoiceStatusBilled, nil + case "rejected", "3": + return onlyoffice.InvoiceStatusRejected, nil + case "paid", "4": + return onlyoffice.InvoiceStatusPaid, nil + default: + var n int + if _, err := fmt.Sscan(s, &n); err != nil || n <= 0 { + return 0, fmt.Errorf("unknown status %q (draft|billed|rejected|paid)", s) + } + return n, nil + } +} + func invoiceDeleteCmd() *cobra.Command { return &cobra.Command{ Use: "delete INVOICE_ID [INVOICE_ID...]", diff --git a/cmd/oo/mails.go b/cmd/oo/mails.go index 02661bb..d6dc4fe 100644 --- a/cmd/oo/mails.go +++ b/cmd/oo/mails.go @@ -229,7 +229,7 @@ Does not send. Open /addons/mail/#drafts to review. if err != nil { return err } - pdf, err := c.InvoicePDFFile(cmd.Context(), strconv.Itoa(invoiceID)) + pdf, err := c.ForceRegenerateInvoicePDF(cmd.Context(), strconv.Itoa(invoiceID)) if err != nil { return err } diff --git a/cmd/oo/main.go b/cmd/oo/main.go index e4825ab..155cebe 100644 --- a/cmd/oo/main.go +++ b/cmd/oo/main.go @@ -6,18 +6,20 @@ // oo projects list | get | milestones | create | update | delete | files (list|upload|download|rename|delete) // oo tasks list | get | create | update | delete | subtask add | files (list|upload|detach) // oo users list | self (alias: oo whoami) -// oo contacts list | get | delete | info-add | dedupe-info +// oo contacts list | get | delete | info-add | merge | dedupe-info // oo persons list | create | delete | dedupe // oo companies list | create | delete | dedupe | dedupe-persons // oo opportunities list | get | create | delete | stages | member-add | dedupe | dedupe-members | fix-titles // oo cases list | create | delete | member-add // oo crm-tasks list | create | delete | categories // oo crm cleanup -// oo mails accounts | folders | list | get | delete -// oo invoices list | get | create | delete | items (list|create|delete) +// oo mails accounts | folders | list | get | draft | attach | draft-invoice | delete +// oo invoices list | get | create | update | pdf | pdf-cleanup | status | delete | items … // oo applications sync // oo catalog scan-contacts | scan-projects | scan-thunderbird | merge | match | apply // +// CRM association rules: docs/crm-associations.md +// // Every list supports `--output/-o json|table` (table is the default). // // Build & install: diff --git a/docs/crm-associations.md b/docs/crm-associations.md new file mode 100644 index 0000000..9877b03 --- /dev/null +++ b/docs/crm-associations.md @@ -0,0 +1,120 @@ +# CRM associations (company ↔ person ↔ deal ↔ project ↔ invoice ↔ mail) + +Operational rules learned from real billing work (AcmeClient INV-2026-01, AcmeProject INV-2026-01). +Tooling: `oo` CLI + this library. Business SSOT remains OnlyOffice (`ASR-0002`). + +## Canonical graph + +One **legal company** owns the relationship. Do not invent a second “bill-to” +company just for PDF layout. + +```text +Company (#CONTACT_ID) +├── Person (GF / buyer contact) oo persons create --company-id +├── Opportunity / Deal oo opportunities … ; member-add company + person +├── Project (hub) oo projects … ; contacts add company + person +│ └── Epic + subtasks +└── Invoice (Draft → …) oo invoices create --contact COMPANY --opportunity DEAL + └── PDF file oo invoices pdf ID + └── Mail draft oo mails draft-invoice --invoice ID --to … +``` + +| Layer | CLI | Must link | +|-------|-----|-----------| +| Company | `oo companies create` | website, email, phone, **one** Billing address | +| Person | `oo persons create --company-id` | job title; never encode employer in `lastName` | +| Deal | `oo opportunities create` + `member-add` | company **and** person as members | +| Project | `oo projects create` + `contacts add` | same company + person | +| Invoice | `oo invoices create --contact COMPANY --opportunity DEAL` | `entityId` at **create** | +| Mail | `oo mails draft-invoice` | attach current PDF; **do not send** until confirmed | + +UI checks (same company card): + +- `#contacts` → person +- `#deals` → opportunity +- `#projects` → hub project +- `#invoices` on the **deal** → invoice (needs `entity`) +- `#files` → preferably **one** current `P-….pdf` + +## Hard rules + +1. **One company per legal entity.** Duplicate “bill-to” contacts empty Deals / + Projects / Contacts tabs and break merge. Prefer + `oo contacts merge FROM INTO` (keeps `INTO`) or `oo companies dedupe`. +2. **Link invoice → deal at create.** + `POST /crm/invoice` with `entityId` + `entityType: 0` (Opportunity). + `oo invoices update … --opportunity` often returns **400** + (“Value does not fall within the expected range”). If the link is missing, + delete the Draft and recreate with `--opportunity`. +3. **Bill To = company id**, not a throwaway contact. Person stays under the + company (`companyId`). Optional `consigneeId` for Empfänger when the portal + template prints it. +4. **Stay Draft until mail is ready.** Billed (`status id=2`) is **not editable** + via content PUT. Going Billed → Draft via `…/crm/invoice/status/1` usually + **does not work** — delete + recreate Draft instead. +5. **Do not regenerate PDF in a loop** without cleanup. Each + `GET …/crm/invoice/{id}/pdf` attaches a new file to the company (and often + the deal). Keep `invoice.fileID`; delete older `P-*.pdf` with + `oo invoices pdf-cleanup ID` / Documents `fileops/delete`. + +## Invoice PDF quirks + +| Symptom | Workaround | +|---------|------------| +| Cached / stale PDF | Touch invoice (Draft PUT that clears `fileID`), then `GET …/pdf` — `oo invoices pdf ID --force` | +| Billing address missing on **new** PDFs | Temporary multiline `companyName` (`Line1\nLine2\n…`) on the **canonical** company → force PDF → restore clean name. Cached `fileID` keeps the multiline Bill To. | +| Separate bill-to company for newlines | **Forbidden** — merge back to the real company | +| Invoice **number** won’t change on PUT | Delete Draft and recreate with the desired number | +| Notizen / Bedingungen spacing | Leading `\n` and blank lines only — no HTML (tags print literally) | +| Issuer NIE / street lines | Organisation profile address (`street` with `\n`), not only terms | + +Status ids commonly used on this portal: `1` Draft, `2` Billed, `3` Rejected, `4` Paid. + +## Mail quirks + +| Symptom | Workaround | +|---------|------------| +| Signature / body cuts Matrix URL at `#` | Plain text `chat: https://matrix.to/#/@user:server` — avoid `` (or encode `#` as `%23` in href) | +| German letter spacing | Blank `

 

` between blocks (`MailHTMLWithBlankParagraphs`) | +| Send | Never auto-send; draft only until the human confirms | + +Prefer OnlyOffice Mail (`/addons/mail/#drafts`) over Gmail MCP for invoice delivery. + +## Project / task quirks + +- Hub title: `CC | Company` (e.g. `DE | AcmeClient Ambulanter Pflegedienst GmbH`). +- Streams = epics/tasks under the hub, not a third title segment (unless the + project itself is a named delivery stream). +- Closing a **subtask**: + `PUT /api/2.0/project/task/{epicId}/{subtaskId}/status` with `status=2`. + `oo tasks update SUBTASK -s closed` returns **404** for subtasks. +- After deleting a CRM contact, `GET /project/contact/{deletedId}` may still + return projects (ghost). Official project contact list should only show live + ids; unlink may 400 if the contact is gone. + +## Merge / cleanup cheat sheet + +```bash +# Keep the human-created company (INTO), drop the duplicate (FROM) +oo contacts merge 1334 1328 + +# Or by normalized name (careful — whole CRM) +oo companies dedupe + +# Invoice ↔ deal must exist at create +oo invoices create --number P-YYYY-NN --contact CONTACT_ID --item N \ + --price 300 --opportunity OPPORTUNITY_ID --language de-DE … + +# Fresh PDF + prune older P-*.pdf on company/deal +oo invoices pdf 41 --force +oo invoices pdf-cleanup INVOICE_ID + +# Mail draft (no send) +oo mails draft-invoice --invoice INVOICE_ID --to info@client.de +``` + +## Related + +- README § invoices / mail / CRM cleanup +- Skill `oo-clients-projects` (Cursor) +- inventar ASR-0014 / `ops/oo-clients-contacts-sync.md` diff --git a/invoices.go b/invoices.go index 52f88ef..6c9cb1d 100644 --- a/invoices.go +++ b/invoices.go @@ -129,6 +129,9 @@ type UpdateInvoiceParams struct { } // UpdateInvoice PUTs a full invoice body (OnlyOffice requires complete payload). +// +// Linking an opportunity via EntityID on an existing invoice often returns HTTP 400 +// on this portal — prefer CreateInvoice with EntityID set. See docs/crm-associations.md. func (c *Client) UpdateInvoice(ctx context.Context, id string, p UpdateInvoiceParams) (map[string]any, error) { inv, err := c.GetInvoice(ctx, id) if err != nil { @@ -236,6 +239,161 @@ func (c *Client) DeleteInvoice(ctx context.Context, id string) (map[string]any, return c.deleteObject(ctx, fmt.Sprintf("/api/2.0/crm/invoice/%s.json", url.PathEscape(id))) } +// Invoice status ids used by OnlyOffice CRM on produktor.io. +const ( + InvoiceStatusDraft = 1 + InvoiceStatusBilled = 2 + InvoiceStatusRejected = 3 + InvoiceStatusPaid = 4 +) + +// SetInvoiceStatus sets CRM invoice status for one or more invoice ids +// (PUT /api/2.0/crm/invoice/status/{statusId} with invoiceids). +// Note: Billed→Draft often does not stick; recreate Draft instead (see docs/crm-associations.md). +func (c *Client) SetInvoiceStatus(ctx context.Context, statusID int, invoiceIDs ...int64) (map[string]any, error) { + if statusID <= 0 { + return nil, fmt.Errorf("status id is required") + } + if len(invoiceIDs) == 0 { + return nil, fmt.Errorf("at least one invoice id is required") + } + ids := make([]string, 0, len(invoiceIDs)) + for _, id := range invoiceIDs { + ids = append(ids, strconv.FormatInt(id, 10)) + } + fields := url.Values{} + fields.Set("invoiceids", strings.Join(ids, ",")) + return c.putFormObject(ctx, fmt.Sprintf("/api/2.0/crm/invoice/status/%d", statusID), fields) +} + +// InvoicePDFFile returns invoice PDF file metadata (id, title, viewUrl). +// Without force, OnlyOffice may return a cached fileID with stale layout. +func (c *Client) InvoicePDFFile(ctx context.Context, invoiceID string) (map[string]any, error) { + id := strings.TrimSpace(invoiceID) + if id == "" { + return nil, fmt.Errorf("InvoicePDFFile: invoice id is required") + } + return c.ResponseObject(ctx, fmt.Sprintf("/api/2.0/crm/invoice/%s/pdf", url.PathEscape(id))) +} + +// ForceRegenerateInvoicePDF clears the cached PDF (Draft touch) then requests a new file. +// No-op touch when the invoice is not editable (e.g. Billed) — falls back to GET /pdf. +func (c *Client) ForceRegenerateInvoicePDF(ctx context.Context, invoiceID string) (map[string]any, error) { + id := strings.TrimSpace(invoiceID) + if id == "" { + return nil, fmt.Errorf("ForceRegenerateInvoicePDF: invoice id is required") + } + inv, err := c.GetInvoice(ctx, id) + if err != nil { + return nil, err + } + canEdit := true + if v, ok := inv["canEdit"].(bool); ok { + canEdit = v + } + if canEdit { + desc := stringField(inv, "description") + // Append/remove a trailing space so PUT clears fileID without visible change. + touch := desc + " " + if strings.HasSuffix(desc, " ") { + touch = strings.TrimSuffix(desc, " ") + } + if _, err := c.UpdateInvoice(ctx, id, UpdateInvoiceParams{ + Description: touch, + DescriptionSet: true, + }); err != nil { + return nil, fmt.Errorf("ForceRegenerateInvoicePDF: clear cache: %w", err) + } + } + return c.InvoicePDFFile(ctx, id) +} + +// ListCRMContactFiles lists Documents attached on a CRM contact card (#files). +func (c *Client) ListCRMContactFiles(ctx context.Context, contactID string) ([]map[string]any, error) { + return c.ResponseArray(ctx, fmt.Sprintf("/api/2.0/crm/contact/%s/files.json", url.PathEscape(contactID))) +} + +// ListOpportunityFiles lists Documents attached on a CRM opportunity. +func (c *Client) ListOpportunityFiles(ctx context.Context, opportunityID string) ([]map[string]any, error) { + return c.ResponseArray(ctx, fmt.Sprintf("/api/2.0/crm/opportunity/%s/files.json", url.PathEscape(opportunityID))) +} + +// PurgeStaleInvoicePDFs deletes older P-*.pdf copies on the invoice contact (and linked +// opportunity) while keeping the invoice's current fileID. Returns deleted file ids. +func (c *Client) PurgeStaleInvoicePDFs(ctx context.Context, invoiceID string) ([]int, error) { + inv, err := c.GetInvoice(ctx, invoiceID) + if err != nil { + return nil, err + } + keep := flexInt(inv["fileID"]) + number := strings.TrimSpace(stringField(inv, "number")) + base := number + for strings.HasSuffix(base, "b") || strings.HasSuffix(base, "B") { + base = base[:len(base)-1] + } + if base == "" { + base = "P-" + } + + seen := map[int]struct{}{} + var candidates []int + addFiles := func(files []map[string]any) { + for _, f := range files { + title := stringField(f, "title") + id := int(flexInt(f["id"])) + if id == 0 || id == int(keep) { + continue + } + if !strings.HasPrefix(title, "P-") { + continue + } + if !strings.HasPrefix(title, base) { + continue + } + if _, ok := seen[id]; ok { + continue + } + seen[id] = struct{}{} + candidates = append(candidates, id) + } + } + + if m, ok := inv["contact"].(map[string]any); ok { + cid := strconv.FormatInt(flexInt(m["id"]), 10) + if cid != "0" { + files, err := c.ListCRMContactFiles(ctx, cid) + if err != nil { + return nil, err + } + addFiles(files) + } + } + if ent, ok := inv["entity"].(map[string]any); ok && ent != nil { + if strings.EqualFold(fmt.Sprint(ent["entityType"]), "opportunity") || flexInt(ent["entityType"]) == 0 { + oid := strconv.FormatInt(flexInt(ent["entityId"]), 10) + if oid != "0" { + files, err := c.ListOpportunityFiles(ctx, oid) + if err != nil { + return nil, err + } + addFiles(files) + } + } + } + + if len(candidates) == 0 { + return nil, nil + } + if err := c.DeleteFiles(ctx, candidates); err != nil { + return nil, err + } + // CRM may still list deleted files briefly; also try CRM unlink. + for _, fid := range candidates { + _, _ = c.deleteObject(ctx, fmt.Sprintf("/api/2.0/crm/files/%d.json", fid)) + } + return candidates, nil +} + // ListInvoiceItems returns catalog invoice items. func (c *Client) ListInvoiceItems(ctx context.Context, count, startIndex int) ([]map[string]any, int, error) { q := url.Values{} diff --git a/mails.go b/mails.go index e5ab907..5689c6c 100644 --- a/mails.go +++ b/mails.go @@ -198,15 +198,6 @@ func (c *Client) AttachMailDocument(ctx context.Context, messageID string, fileI return c.postFormObject(ctx, fmt.Sprintf("/api/2.0/mail/messages/%s/document", url.PathEscape(id)), fields) } -// InvoicePDFFile regenerates/returns the invoice PDF file metadata (id, title, viewUrl). -func (c *Client) InvoicePDFFile(ctx context.Context, invoiceID string) (map[string]any, error) { - id := strings.TrimSpace(invoiceID) - if id == "" { - return nil, fmt.Errorf("InvoicePDFFile: invoice id is required") - } - return c.ResponseObject(ctx, fmt.Sprintf("/api/2.0/crm/invoice/%s/pdf", url.PathEscape(id))) -} - // PlainTextToMailHTML turns plain text into simple HTML paragraphs for drafts. // If s already looks like HTML, it is returned unchanged. func PlainTextToMailHTML(s string) string {