x
"}}}, + {ID: "a2", CollectionID: "c2", DefaultLocale: "en", Variants: map[string]ArticleVariant{"en": {Locale: "en", Title: "y", BodyHTML: "y
"}}}, + }, + Authors: map[string]Author{}, + Locales: []string{"en"}, + } + resolver := NewAuthorResolver(corpus.Authors, map[string]int{}, 1) + plan := Plan(corpus, Selections{SourceHCID: "hc1", Target: PortalTarget{CreateSlug: "p"}, Locales: []string{"en"}}, resolver, NewState("i", "w", "hc1"), nil) + + slugByColl := map[string]string{} + for _, pc := range plan.Categories { + slugByColl[pc.CollectionID] = pc.Slug + } + if slugByColl["c1"] == "" || slugByColl["c2"] == "" { + t.Fatalf("missing slugs: %#v", slugByColl) + } + if slugByColl["c1"] == slugByColl["c2"] { + t.Fatalf("duplicate-named collections must get distinct slugs, both = %q", slugByColl["c1"]) + } +} + +func TestPlanAvoidsReservedCategorySlugs(t *testing.T) { + corpus := &Corpus{ + HelpCenter: HelpCenter{ID: "hc1", DefaultLocale: "en"}, + Collections: []Collection{{ID: "c1", Names: map[string]string{"en": "Getting Started"}}}, + Articles: []Article{ + {ID: "a1", CollectionID: "c1", DefaultLocale: "en", Variants: map[string]ArticleVariant{"en": {Locale: "en", Title: "x", BodyHTML: "x
"}}}, + }, + Authors: map[string]Author{}, + Locales: []string{"en"}, + } + resolver := NewAuthorResolver(corpus.Authors, map[string]int{}, 1) + // "getting-started" already exists in the portal. + plan := Plan(corpus, Selections{SourceHCID: "hc1", Target: PortalTarget{ExistingSlug: "p"}, Locales: []string{"en"}}, resolver, NewState("i", "w", "hc1"), []string{"getting-started"}) + + if len(plan.Categories) != 1 { + t.Fatalf("categories = %d, want 1", len(plan.Categories)) + } + if plan.Categories[0].Slug == "getting-started" { + t.Fatalf("slug should avoid the reserved one, got %q", plan.Categories[0].Slug) + } +} diff --git a/internal/importer/intercom/client.go b/internal/importer/intercom/client.go new file mode 100644 index 0000000..9ef94b5 --- /dev/null +++ b/internal/importer/intercom/client.go @@ -0,0 +1,228 @@ +// Package intercom is a small, hand-wrapped client for the Intercom REST API +// (help centers, collections, articles, admins) plus a Source implementation +// that maps Intercom data into the provider-neutral importer IR. It depends +// only on the standard library — no Intercom SDK. +package intercom + +import ( + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "net/url" + "strconv" + "strings" + "time" +) + +const ( + defaultBaseURL = "https://api.intercom.io" + defaultVersion = "2.11" + defaultPerPage = 150 + maxRetries = 5 +) + +// Client is an Intercom REST client with bearer auth, version header, cursor +// pagination, and bounded retry/backoff on 429 and 5xx responses. +type Client struct { + baseURL string + token string + version string + httpClient *http.Client + sleep func(time.Duration) +} + +// Option configures a Client. +type Option func(*Client) + +// WithHTTPClient injects a custom *http.Client (used in tests). +func WithHTTPClient(h *http.Client) Option { + return func(c *Client) { c.httpClient = h } +} + +// WithVersion overrides the Intercom-Version header. +func WithVersion(v string) Option { + return func(c *Client) { + if strings.TrimSpace(v) != "" { + c.version = v + } + } +} + +// withSleep overrides the backoff sleep (used in tests to avoid real waits). +func withSleep(fn func(time.Duration)) Option { + return func(c *Client) { c.sleep = fn } +} + +// NewClient builds an Intercom client. An empty baseURL defaults to +// https://api.intercom.io. +func NewClient(baseURL, token string, opts ...Option) *Client { + c := &Client{ + baseURL: strings.TrimSuffix(strings.TrimSpace(baseURL), "/"), + token: token, + version: defaultVersion, + httpClient: &http.Client{Timeout: 60 * time.Second}, + sleep: time.Sleep, + } + if c.baseURL == "" { + c.baseURL = defaultBaseURL + } + for _, opt := range opts { + opt(c) + } + return c +} + +func (c *Client) get(ctx context.Context, path string, query url.Values, out any) error { + full := c.baseURL + path + if len(query) > 0 { + full += "?" + query.Encode() + } + + var lastErr error + for attempt := 0; attempt <= maxRetries; attempt++ { + req, err := http.NewRequestWithContext(ctx, http.MethodGet, full, nil) + if err != nil { + return err + } + req.Header.Set("Authorization", "Bearer "+c.token) + req.Header.Set("Intercom-Version", c.version) + req.Header.Set("Accept", "application/json") + + resp, err := c.httpClient.Do(req) + if err != nil { + lastErr = fmt.Errorf("intercom request failed: %w", err) + if attempt < maxRetries { + c.sleep(backoff(attempt, 0)) + continue + } + return lastErr + } + + body, readErr := io.ReadAll(resp.Body) + _ = resp.Body.Close() + if readErr != nil { + return fmt.Errorf("read intercom response: %w", readErr) + } + + if resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= 500 { + lastErr = fmt.Errorf("intercom API %d: %s", resp.StatusCode, snippet(body)) + if attempt < maxRetries { + c.sleep(backoff(attempt, retryAfter(resp.Header))) + continue + } + return lastErr + } + if resp.StatusCode >= 400 { + return fmt.Errorf("intercom API %d: %s", resp.StatusCode, snippet(body)) + } + if out == nil { + return nil + } + if err := json.Unmarshal(body, out); err != nil { + return fmt.Errorf("decode intercom response: %w", err) + } + return nil + } + return lastErr +} + +// fetchList fetches every page of an Intercom cursor-paginated list endpoint. +func fetchList[T any](ctx context.Context, c *Client, path string) ([]T, error) { + var all []T + startingAfter := "" + guard := 0 + for { + q := url.Values{} + q.Set("per_page", strconv.Itoa(defaultPerPage)) + if startingAfter != "" { + q.Set("starting_after", startingAfter) + } + + var env listEnvelope[T] + if err := c.get(ctx, path, q, &env); err != nil { + return nil, err + } + all = append(all, env.Data...) + + next := env.Pages.nextCursor() + if next == "" { + break + } + startingAfter = next + + // Safety guard against a misbehaving cursor that never terminates. + guard++ + if guard > 10000 { + break + } + } + return all, nil +} + +// Me returns the authenticated admin and workspace info (used for validation). +func (c *Client) Me(ctx context.Context) (*meResponse, error) { + var me meResponse + if err := c.get(ctx, "/me", nil, &me); err != nil { + return nil, err + } + return &me, nil +} + +// ListAdmins returns all teammates. +func (c *Client) ListAdmins(ctx context.Context) ([]admin, error) { + var list adminList + if err := c.get(ctx, "/admins", nil, &list); err != nil { + return nil, err + } + return list.Admins, nil +} + +// ListHelpCenters returns all help centers. +func (c *Client) ListHelpCenters(ctx context.Context) ([]helpCenter, error) { + return fetchList[helpCenter](ctx, c, "/help_center/help_centers") +} + +// ListCollections returns all collections across help centers. +func (c *Client) ListCollections(ctx context.Context) ([]collection, error) { + return fetchList[collection](ctx, c, "/help_center/collections") +} + +// ListArticles returns all articles in the workspace. +func (c *Client) ListArticles(ctx context.Context) ([]article, error) { + return fetchList[article](ctx, c, "/articles") +} + +// backoff returns the wait before a retry: honors a server-provided +// Retry-After (seconds) when present, else exponential (0.5s * 2^attempt) +// capped at 30s. +func backoff(attempt int, retryAfterSecs int) time.Duration { + if retryAfterSecs > 0 { + return time.Duration(retryAfterSecs) * time.Second + } + d := 500 * time.Millisecond * time.Duration(1<EN body
","author_id":500,"state":"published","default_locale":"en","url":"https://h/en/articles/1001-setup", + "translated_content":{"type":"article_translated_content", + "fr":{"type":"article_content","title":"Configuration","description":"df","body":"FR body
","author_id":500,"state":"published"}}}, + {"id":"2002","parent_id":99,"title":"Other HC article","body":"x","default_locale":"en"} + ],"pages":{"next":null},"total_count":2}`)) + default: + http.Error(w, "unexpected path: "+r.URL.Path, http.StatusNotFound) + } + })) +} + +func TestScanMapsToIR(t *testing.T) { + server := fakeIntercom(t) + t.Cleanup(server.Close) + + src := New(server.URL, "tok", WithHTTPClient(server.Client())) + corpus, err := src.Scan(context.Background(), "hc1") + if err != nil { + t.Fatalf("Scan: %v", err) + } + + // Only hc1's collection is kept. + if len(corpus.Collections) != 1 || corpus.Collections[0].ID != "10" { + t.Fatalf("collections = %#v, want only id 10", corpus.Collections) + } + coll := corpus.Collections[0] + if coll.Names["en"] != "Getting Started" || coll.Names["fr"] != "Commencer" { + t.Errorf("collection names = %#v, want en+fr", coll.Names) + } + + // Article 2002 belongs to collection 99 (not in hc1) -> excluded. + if len(corpus.Articles) != 1 || corpus.Articles[0].ID != "1001" { + t.Fatalf("articles = %#v, want only 1001", corpus.Articles) + } + art := corpus.Articles[0] + if art.CollectionID != "10" { + t.Errorf("article collection = %q, want 10", art.CollectionID) + } + if art.DefaultLocale != "en" { + t.Errorf("default locale = %q, want en", art.DefaultLocale) + } + if len(art.Variants) != 2 { + t.Fatalf("variants = %#v, want en+fr", art.Variants) + } + if art.Variants["en"].BodyHTML != "EN body
" { + t.Errorf("en body = %q", art.Variants["en"].BodyHTML) + } + if art.Variants["fr"].Title != "Configuration" { + t.Errorf("fr title = %q, want Configuration", art.Variants["fr"].Title) + } + + // author_id (number 500) resolves to admin id "500". + if a, ok := corpus.Authors["500"]; !ok || a.Email != "ada@acme.com" { + t.Errorf("authors = %#v, want 500 -> ada@acme.com", corpus.Authors) + } + + // Locales: default first. + if len(corpus.Locales) != 2 || corpus.Locales[0] != "en" || corpus.Locales[1] != "fr" { + t.Errorf("locales = %#v, want [en fr]", corpus.Locales) + } +} + +func TestValidateReturnsWorkspaceID(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != "/me" { + http.Error(w, "unexpected", http.StatusNotFound) + return + } + _, _ = w.Write([]byte(`{"type":"admin","id":"42","email":"me@acme.com","app":{"id_code":"ws_abc"}}`)) + })) + t.Cleanup(server.Close) + + src := New(server.URL, "tok", WithHTTPClient(server.Client())) + ws, err := src.Validate(context.Background()) + if err != nil { + t.Fatalf("Validate: %v", err) + } + if ws != "ws_abc" { + t.Fatalf("workspace = %q, want ws_abc", ws) + } +} diff --git a/internal/importer/intercom/types.go b/internal/importer/intercom/types.go new file mode 100644 index 0000000..0fa773a --- /dev/null +++ b/internal/importer/intercom/types.go @@ -0,0 +1,166 @@ +package intercom + +import ( + "encoding/json" + "net/url" + "strings" +) + +// flexID normalizes Intercom ids that arrive as either JSON strings or numbers +// (e.g. collection ids are strings, but an article's parent_id/author_id are +// numbers) into a single string representation so they can be compared. +type flexID string + +func (f *flexID) UnmarshalJSON(b []byte) error { + s := strings.TrimSpace(string(b)) + if s == "" || s == "null" { + *f = "" + return nil + } + if s[0] == '"' { + var str string + if err := json.Unmarshal(b, &str); err != nil { + return err + } + *f = flexID(str) + return nil + } + *f = flexID(s) + return nil +} + +func (f flexID) String() string { return string(f) } + +// listEnvelope is Intercom's standard cursor-paginated list response. +type listEnvelope[T any] struct { + Type string `json:"type"` + Data []T `json:"data"` + Pages *pages `json:"pages"` + TotalCount int `json:"total_count"` +} + +type pages struct { + Next json.RawMessage `json:"next"` + Page int `json:"page"` + PerPage int `json:"per_page"` + TotalPages int `json:"total_pages"` +} + +// nextCursor extracts the starting_after cursor from pages.next, which may be +// either an object {page, starting_after} (v2.x) or a bare URL string. +func (p *pages) nextCursor() string { + if p == nil || len(p.Next) == 0 || string(p.Next) == "null" { + return "" + } + var obj struct { + StartingAfter string `json:"starting_after"` + } + if err := json.Unmarshal(p.Next, &obj); err == nil && obj.StartingAfter != "" { + return obj.StartingAfter + } + var s string + if err := json.Unmarshal(p.Next, &s); err == nil && s != "" { + // next may be a full URL or a bare query string. Parse it and read the + // decoded starting_after value, so percent-encoded cursors (%2F, %3D…) + // are not re-encoded when we put them back on the next request. + if u, err := url.Parse(s); err == nil && u.RawQuery != "" { + if sa := u.Query().Get("starting_after"); sa != "" { + return sa + } + } + if vals, err := url.ParseQuery(s); err == nil { + if sa := vals.Get("starting_after"); sa != "" { + return sa + } + } + } + return "" +} + +// meResponse is GET /me — the authenticated admin plus workspace (app) info. +type meResponse struct { + Type string `json:"type"` + ID flexID `json:"id"` + Email string `json:"email"` + App struct { + IDCode string `json:"id_code"` + Name string `json:"name"` + } `json:"app"` +} + +// adminList is GET /admins (note: uses "admins", not the standard "data"). +type adminList struct { + Type string `json:"type"` + Admins []admin `json:"admins"` +} + +type admin struct { + ID flexID `json:"id"` + Name string `json:"name"` + Email string `json:"email"` +} + +type helpCenter struct { + ID flexID `json:"id"` + DisplayName string `json:"display_name"` + Identifier string `json:"identifier"` + WorkspaceID string `json:"workspace_id"` +} + +type collection struct { + ID flexID `json:"id"` + Name string `json:"name"` + Description string `json:"description"` + ParentID flexID `json:"parent_id"` + HelpCenterID flexID `json:"help_center_id"` + Order int `json:"order"` + TranslatedContent json.RawMessage `json:"translated_content"` +} + +type article struct { + ID flexID `json:"id"` + ParentID flexID `json:"parent_id"` + ParentType string `json:"parent_type"` + Title string `json:"title"` + Description string `json:"description"` + Body string `json:"body"` + AuthorID flexID `json:"author_id"` + State string `json:"state"` + URL string `json:"url"` + DefaultLocale string `json:"default_locale"` + TranslatedContent json.RawMessage `json:"translated_content"` +} + +// localizedContent is one locale entry inside a translated_content object. +type localizedContent struct { + Name string `json:"name"` // collections + Title string `json:"title"` // articles + Description string `json:"description"` + Body string `json:"body"` + AuthorID flexID `json:"author_id"` + State string `json:"state"` +} + +// parseTranslatedContent unmarshals an Intercom translated_content object, +// skipping its non-locale "type" key, into a locale -> content map. +func parseTranslatedContent(raw json.RawMessage) map[string]localizedContent { + if len(raw) == 0 || string(raw) == "null" { + return nil + } + var byKey map[string]json.RawMessage + if err := json.Unmarshal(raw, &byKey); err != nil { + return nil + } + out := make(map[string]localizedContent) + for key, val := range byKey { + if key == "type" { + continue + } + var c localizedContent + if err := json.Unmarshal(val, &c); err != nil { + continue + } + out[key] = c + } + return out +} diff --git a/internal/importer/intercom/types_test.go b/internal/importer/intercom/types_test.go new file mode 100644 index 0000000..24c8f8a --- /dev/null +++ b/internal/importer/intercom/types_test.go @@ -0,0 +1,39 @@ +package intercom + +import ( + "encoding/json" + "testing" +) + +func TestNextCursorObjectForm(t *testing.T) { + p := &pages{Next: json.RawMessage(`{"page":2,"starting_after":"abc123"}`)} + if got := p.nextCursor(); got != "abc123" { + t.Fatalf("nextCursor = %q, want abc123", got) + } +} + +func TestNextCursorURLFormDecodesPercentEncoding(t *testing.T) { + // A full-URL cursor whose starting_after is percent-encoded (%3D == "="). + // The old substring extraction returned it still-encoded, which got + // double-encoded on the next request and skipped pages. + p := &pages{Next: json.RawMessage(`"https://api.intercom.io/articles?per_page=150&starting_after=WzE3MF0%3D"`)} + if got := p.nextCursor(); got != "WzE3MF0=" { + t.Fatalf("nextCursor = %q, want WzE3MF0= (decoded)", got) + } +} + +func TestNextCursorBareQueryForm(t *testing.T) { + p := &pages{Next: json.RawMessage(`"starting_after=a%2Fb"`)} + if got := p.nextCursor(); got != "a/b" { + t.Fatalf("nextCursor = %q, want a/b (decoded)", got) + } +} + +func TestNextCursorNullOrEmpty(t *testing.T) { + if got := (&pages{Next: json.RawMessage(`null`)}).nextCursor(); got != "" { + t.Errorf("null next = %q, want empty", got) + } + if got := (&pages{}).nextCursor(); got != "" { + t.Errorf("absent next = %q, want empty", got) + } +} diff --git a/internal/importer/ir.go b/internal/importer/ir.go new file mode 100644 index 0000000..12583c8 --- /dev/null +++ b/internal/importer/ir.go @@ -0,0 +1,170 @@ +// Package importer is a source-agnostic engine for importing Help Center +// content into Chatwoot. Providers (Intercom today; Crisp/Zendesk later) +// implement the Source interface and map their data into the provider-neutral +// intermediate representation (IR) defined here. The engine then plans and +// executes the writes against Chatwoot via a Sink. +// +// The engine is intentionally non-interactive: all prompting lives in the CLI +// layer, which passes the user's choices in as a Selections value. +package importer + +// HelpCenter is a selectable source help center. +type HelpCenter struct { + ID string + Name string + DefaultLocale string +} + +// Collection is a provider-neutral category/section. Nesting is expressed via +// ParentID. Names/Descriptions are keyed by locale and must include the +// collection's default-locale name. +type Collection struct { + ID string + ParentID string + Names map[string]string + Descriptions map[string]string + Order int +} + +// Name returns the best name for a locale, falling back to the default locale +// then any available name. +func (c Collection) Name(locale, defaultLocale string) string { + if n, ok := c.Names[locale]; ok && n != "" { + return n + } + if n, ok := c.Names[defaultLocale]; ok && n != "" { + return n + } + for _, n := range c.Names { + if n != "" { + return n + } + } + return c.ID +} + +// Article carries the default-locale body as the root plus per-locale variants. +type Article struct { + ID string + CollectionID string + DefaultLocale string + AuthorID string + Variants map[string]ArticleVariant + SourceURL string +} + +// ArticleVariant is one localized rendition of an article. +type ArticleVariant struct { + Locale string + Title string + Description string + BodyHTML string + AuthorID string // per-locale author override; falls back to Article.AuthorID + State string // provider state, kept for reporting; imports always write draft +} + +// Author is a provider teammate/admin used for author matching. +type Author struct { + ID string + Email string + Name string +} + +// Corpus is the fully-scanned source graph for one help center. +type Corpus struct { + HelpCenter HelpCenter + Collections []Collection + Articles []Article + Authors map[string]Author + Locales []string // derived during scan; default locale first +} + +// PortalTarget describes the chosen Chatwoot portal: either an existing slug +// or a new portal to create. +type PortalTarget struct { + ExistingSlug string + CreateName string + CreateSlug string +} + +// IsCreate reports whether a new portal should be created. +func (t PortalTarget) IsCreate() bool { return t.ExistingSlug == "" } + +// Slug returns the portal slug (existing or to-be-created). +func (t PortalTarget) Slug() string { + if t.ExistingSlug != "" { + return t.ExistingSlug + } + return t.CreateSlug +} + +// Selections is the user's interactive choices, built by the CLI layer and +// passed to Plan. +type Selections struct { + SourceHCID string + Target PortalTarget + Locales []string // locales chosen for import; gates non-root variants +} + +// --------------------------------------------------------------------------- +// Plan — the resolved, ordered set of writes Execute will perform. Built by +// Plan() with no network calls (author resolution uses pre-fetched maps). +// --------------------------------------------------------------------------- + +// PlannedCategory is one category create (a collection in a specific locale). +type PlannedCategory struct { + CollectionID string + ParentCollectionID string + Locale string + IsRoot bool // root = the collection's default-locale category + Name string + Description string + Slug string + Skip bool // already recorded in state +} + +// PlannedArticle is one article create (an article variant in a locale). +type PlannedArticle struct { + ArticleID string + CollectionID string + Locale string + RootLocale string // the article's default locale (the root variant's locale) + IsRoot bool // root = the article's default-locale variant + Title string + Description string + BodyHTML string // raw; Execute transforms images/embeds before writing + AuthorID int // resolved Chatwoot user id + Skip bool +} + +// ImportPlan is the full ordered plan plus summary metadata. +type ImportPlan struct { + Portal PortalTarget + DefaultLocale string // corpus default locale (the per-collection root locale) + PortalLocales []string // effective allowed locales to ensure on the portal + Categories []PlannedCategory + Articles []PlannedArticle + AuthorStats AuthorStats +} + +// AuthorStats summarizes author matching for the plan/summary. +type AuthorStats struct { + Matched int + Fallback int +} + +// Result is the outcome of Execute, for the final summary. +type Result struct { + PortalSlug string + PortalCreated bool + CategoriesCreated int + CategoriesSkipped int + ArticlesCreated int + ArticlesSkipped int + ImagesSwapped int + ImagesFailed int + EmbedsRewritten int + UncategorizedCount int + Failures []FailureRec + AuthorStats AuthorStats +} diff --git a/internal/importer/source.go b/internal/importer/source.go new file mode 100644 index 0000000..d319a84 --- /dev/null +++ b/internal/importer/source.go @@ -0,0 +1,24 @@ +package importer + +import "context" + +// Source is the provider abstraction. Intercom is the first implementation; +// Crisp/Zendesk can be added later as new packages without touching the engine. +type Source interface { + // Name is a stable provider key used in the state-file id (e.g. "intercom"). + Name() string + + // Validate confirms credentials work and returns a stable workspace + // identifier used for state keying. + Validate(ctx context.Context) (workspaceID string, err error) + + // ListHelpCenters returns the selectable source help centers. Providers + // without a multi-help-center concept return a single synthetic entry. + ListHelpCenters(ctx context.Context) ([]HelpCenter, error) + + // Scan pulls the full IR graph for one help center: collections (with + // parents), articles (with per-locale variants + author ids), authors, and + // the derived locale set. Implementations handle pagination and rate + // limiting internally. + Scan(ctx context.Context, helpCenterID string) (*Corpus, error) +} diff --git a/internal/importer/state.go b/internal/importer/state.go new file mode 100644 index 0000000..4297561 --- /dev/null +++ b/internal/importer/state.go @@ -0,0 +1,173 @@ +package importer + +import ( + "crypto/sha256" + "encoding/hex" + "encoding/json" + "fmt" + "os" + "path/filepath" + "time" +) + +// stateVersion is the on-disk schema version. +const stateVersion = 1 + +// ItemRef is a created Chatwoot record (category or article). +type ItemRef struct { + ID int `json:"id"` + Slug string `json:"slug,omitempty"` +} + +// FailureRec records a per-item failure for reporting and retry. +type FailureRec struct { + Kind string `json:"kind"` + Error string `json:"error"` + At string `json:"at"` +} + +// PortalRef is the resolved target portal. +type PortalRef struct { + Slug string `json:"slug"` + ID int `json:"id"` +} + +// State is the resumable import state persisted under ~/.chatwoot/imports/. +// Categories and Articles map a source id -> locale -> created Chatwoot record. +type State struct { + Version int `json:"version"` + Provider string `json:"provider"` + WorkspaceID string `json:"workspace_id"` + SourceHCID string `json:"source_help_center_id"` + TargetPortal PortalRef `json:"target_portal"` + Locales []string `json:"locales"` + Categories map[string]map[string]ItemRef `json:"categories"` + Articles map[string]map[string]ItemRef `json:"articles"` + Failures map[string]FailureRec `json:"failures"` + UpdatedAt string `json:"updated_at"` +} + +// NewState returns an initialized, empty state. +func NewState(provider, workspaceID, sourceHCID string) *State { + return &State{ + Version: stateVersion, + Provider: provider, + WorkspaceID: workspaceID, + SourceHCID: sourceHCID, + Categories: map[string]map[string]ItemRef{}, + Articles: map[string]map[string]ItemRef{}, + Failures: map[string]FailureRec{}, + } +} + +// StateKey derives a stable file key from the import coordinates. Target slug +// is known before any write (portal slugs are used verbatim by Chatwoot). +func StateKey(provider, workspaceID, sourceHCID, targetSlug string) string { + sum := sha256.Sum256([]byte(provider + ":" + workspaceID + ":" + sourceHCID + ":" + targetSlug)) + return hex.EncodeToString(sum[:])[:16] +} + +// StatePath returns the on-disk path for a state key within dir. +func StatePath(dir, key string) string { + return filepath.Join(dir, key+".json") +} + +// LoadState reads state from path, returning nil (not an error) when the file +// does not exist. +func LoadState(path string) (*State, error) { + data, err := os.ReadFile(path) + if err != nil { + if os.IsNotExist(err) { + return nil, nil + } + return nil, fmt.Errorf("failed to read import state: %w", err) + } + var s State + if err := json.Unmarshal(data, &s); err != nil { + return nil, fmt.Errorf("failed to parse import state: %w", err) + } + s.ensureMaps() + return &s, nil +} + +func (s *State) ensureMaps() { + if s.Categories == nil { + s.Categories = map[string]map[string]ItemRef{} + } + if s.Articles == nil { + s.Articles = map[string]map[string]ItemRef{} + } + if s.Failures == nil { + s.Failures = map[string]FailureRec{} + } +} + +// Save writes state atomically (tmp + rename) with 0600 perms, creating the +// parent directory (0700) if needed. +func (s *State) Save(path string) error { + s.UpdatedAt = time.Now().UTC().Format(time.RFC3339) + dir := filepath.Dir(path) + if err := os.MkdirAll(dir, 0o700); err != nil { + return fmt.Errorf("failed to create import state dir: %w", err) + } + data, err := json.MarshalIndent(s, "", " ") + if err != nil { + return err + } + tmp := path + ".tmp" + if err := os.WriteFile(tmp, data, 0o600); err != nil { + return fmt.Errorf("failed to write import state: %w", err) + } + if err := os.Rename(tmp, path); err != nil { + return fmt.Errorf("failed to commit import state: %w", err) + } + return nil +} + +// CategoryRef returns the recorded category for a collection+locale, if any. +func (s *State) CategoryRef(collectionID, locale string) (ItemRef, bool) { + byLocale, ok := s.Categories[collectionID] + if !ok { + return ItemRef{}, false + } + ref, ok := byLocale[locale] + return ref, ok +} + +// SetCategory records a created category and clears any prior failure for it. +func (s *State) SetCategory(collectionID, locale string, ref ItemRef) { + if s.Categories[collectionID] == nil { + s.Categories[collectionID] = map[string]ItemRef{} + } + s.Categories[collectionID][locale] = ref + delete(s.Failures, categoryKey(collectionID, locale)) +} + +// ArticleRef returns the recorded article for an article+locale, if any. +func (s *State) ArticleRef(articleID, locale string) (ItemRef, bool) { + byLocale, ok := s.Articles[articleID] + if !ok { + return ItemRef{}, false + } + ref, ok := byLocale[locale] + return ref, ok +} + +// SetArticle records a created article and clears any prior failure for it. +func (s *State) SetArticle(articleID, locale string, ref ItemRef) { + if s.Articles[articleID] == nil { + s.Articles[articleID] = map[string]ItemRef{} + } + s.Articles[articleID][locale] = ref + delete(s.Failures, articleKey(articleID, locale)) +} + +// RecordFailure stores a per-item failure keyed by its composite id. +func (s *State) RecordFailure(key, kind, errMsg string) { + s.Failures[key] = FailureRec{Kind: kind, Error: errMsg, At: time.Now().UTC().Format(time.RFC3339)} +} + +func categoryKey(collectionID, locale string) string { + return "category:" + collectionID + ":" + locale +} +func articleKey(articleID, locale string) string { return "article:" + articleID + ":" + locale } diff --git a/internal/importer/state_test.go b/internal/importer/state_test.go new file mode 100644 index 0000000..5e0721d --- /dev/null +++ b/internal/importer/state_test.go @@ -0,0 +1,97 @@ +package importer + +import ( + "os" + "path/filepath" + "runtime" + "testing" +) + +func TestStateKeyIsStableAndCoordinateSensitive(t *testing.T) { + a := StateKey("intercom", "ws1", "hc1", "acme-support") + b := StateKey("intercom", "ws1", "hc1", "acme-support") + if a != b { + t.Fatalf("key not stable: %q != %q", a, b) + } + if a == StateKey("intercom", "ws1", "hc1", "other-portal") { + t.Fatal("different target slug should produce a different key") + } + if len(a) != 16 { + t.Fatalf("key length = %d, want 16", len(a)) + } +} + +func TestLoadStateMissingReturnsNil(t *testing.T) { + s, err := LoadState(filepath.Join(t.TempDir(), "nope.json")) + if err != nil { + t.Fatalf("LoadState: %v", err) + } + if s != nil { + t.Fatalf("expected nil state for missing file, got %#v", s) + } +} + +func TestStateSaveLoadRoundTripAndPerms(t *testing.T) { + dir := t.TempDir() + path := StatePath(dir, "key123") + + s := NewState("intercom", "ws1", "hc1") + s.TargetPortal = PortalRef{Slug: "acme-support", ID: 7} + s.Locales = []string{"en", "fr"} + s.SetCategory("coll1", "en", ItemRef{ID: 10, Slug: "faq"}) + s.SetArticle("art1", "en", ItemRef{ID: 100, Slug: "hello"}) + + if err := s.Save(path); err != nil { + t.Fatalf("Save: %v", err) + } + + if runtime.GOOS != "windows" { + info, err := os.Stat(path) + if err != nil { + t.Fatalf("stat: %v", err) + } + if perm := info.Mode().Perm(); perm != 0o600 { + t.Errorf("perm = %o, want 600", perm) + } + } + + loaded, err := LoadState(path) + if err != nil { + t.Fatalf("LoadState: %v", err) + } + if loaded == nil { + t.Fatal("expected loaded state") + } + if ref, ok := loaded.CategoryRef("coll1", "en"); !ok || ref.ID != 10 { + t.Errorf("category ref = %#v ok=%v, want id 10", ref, ok) + } + if ref, ok := loaded.ArticleRef("art1", "en"); !ok || ref.ID != 100 { + t.Errorf("article ref = %#v ok=%v, want id 100", ref, ok) + } + if loaded.TargetPortal.ID != 7 { + t.Errorf("portal id = %d, want 7", loaded.TargetPortal.ID) + } +} + +func TestSetCategoryClearsFailure(t *testing.T) { + s := NewState("intercom", "ws1", "hc1") + key := categoryKey("coll1", "fr") + s.RecordFailure(key, "category", "boom") + if _, ok := s.Failures[key]; !ok { + t.Fatal("failure not recorded") + } + s.SetCategory("coll1", "fr", ItemRef{ID: 5}) + if _, ok := s.Failures[key]; ok { + t.Fatal("failure should be cleared after success") + } +} + +func TestMissingRefsReturnFalse(t *testing.T) { + s := NewState("intercom", "ws1", "hc1") + if _, ok := s.CategoryRef("nope", "en"); ok { + t.Error("expected no category ref") + } + if _, ok := s.ArticleRef("nope", "en"); ok { + t.Error("expected no article ref") + } +} diff --git a/internal/importer/transform.go b/internal/importer/transform.go new file mode 100644 index 0000000..09a84a7 --- /dev/null +++ b/internal/importer/transform.go @@ -0,0 +1,187 @@ +package importer + +import ( + "bytes" + "strings" + + "golang.org/x/net/html" +) + +// ImageUploader re-hosts a remote image URL and returns the new hosted URL. +// It is injected so the transform stays pure/testable; in production it wraps +// the Chatwoot upload endpoint. +type ImageUploader func(srcURL string) (newURL string, err error) + +// TransformResult is the rewritten body plus per-article counters. +type TransformResult struct { + HTML string + ImagesSwapped int + ImagesFailed int + EmbedsRewritten int +} + +// TransformBody rewrites an HTML article body:
= 1 && n <= len(options) {
+ return n - 1, nil
+ }
+ fmt.Fprintf(p.w, "Please enter a number between 1 and %d.\n", len(options))
+ }
+}
+
+// SelectMany shows a numbered list and reads a comma-separated set of choices.
+// "all" (when allowAll) selects everything. Re-prompts on invalid input.
+func (p *TermPrompter) SelectMany(label string, options []string, allowAll bool) ([]int, error) {
+ if len(options) == 0 {
+ return nil, fmt.Errorf("no options to choose from")
+ }
+ p.printOptions(label, options)
+ hint := "Enter numbers (comma-separated)"
+ if allowAll {
+ hint += " or 'all'"
+ }
+ for {
+ fmt.Fprintf(p.w, "%s: ", hint)
+ line, err := p.readLine()
+ if err != nil {
+ return nil, err
+ }
+ if allowAll && strings.EqualFold(line, "all") {
+ idxs := make([]int, len(options))
+ for i := range options {
+ idxs[i] = i
+ }
+ return idxs, nil
+ }
+ idxs, ok := parseIndexList(line, len(options))
+ if ok && len(idxs) > 0 {
+ return idxs, nil
+ }
+ fmt.Fprintf(p.w, "Please enter one or more numbers between 1 and %d, separated by commas.\n", len(options))
+ }
+}
+
+// parseIndexList parses "1, 3,2" into a deduplicated, ordered []int of 0-based
+// indices. Returns ok=false if any token is not a valid in-range number.
+func parseIndexList(line string, n int) ([]int, bool) {
+ if strings.TrimSpace(line) == "" {
+ return nil, false
+ }
+ seen := make(map[int]bool)
+ var out []int
+ for tok := range strings.SplitSeq(line, ",") {
+ tok = strings.TrimSpace(tok)
+ if tok == "" {
+ continue
+ }
+ v, err := strconv.Atoi(tok)
+ if err != nil || v < 1 || v > n {
+ return nil, false
+ }
+ if !seen[v-1] {
+ seen[v-1] = true
+ out = append(out, v-1)
+ }
+ }
+ return out, true
+}
+
+// Input reads a line, returning def on empty input.
+func (p *TermPrompter) Input(label, def string) (string, error) {
+ if def != "" {
+ fmt.Fprintf(p.w, "%s [%s]: ", label, def)
+ } else {
+ fmt.Fprintf(p.w, "%s: ", label)
+ }
+ line, err := p.readLine()
+ if err != nil {
+ return "", err
+ }
+ if line == "" {
+ return def, nil
+ }
+ return line, nil
+}
+
+// Confirm asks a yes/no question, defaulting to no on empty input.
+func (p *TermPrompter) Confirm(label string) (bool, error) {
+ fmt.Fprintf(p.w, "%s [y/N]: ", label)
+ line, err := p.readLine()
+ if err != nil {
+ return false, err
+ }
+ switch strings.ToLower(line) {
+ case "y", "yes":
+ return true, nil
+ default:
+ return false, nil
+ }
+}
diff --git a/internal/prompt/prompt_test.go b/internal/prompt/prompt_test.go
new file mode 100644
index 0000000..8a71884
--- /dev/null
+++ b/internal/prompt/prompt_test.go
@@ -0,0 +1,120 @@
+package prompt
+
+import (
+ "bytes"
+ "strings"
+ "testing"
+)
+
+func newTest(input string) (*TermPrompter, *bytes.Buffer) {
+ var out bytes.Buffer
+ return NewTermPrompter(strings.NewReader(input), &out), &out
+}
+
+func TestSelectOne(t *testing.T) {
+ p, _ := newTest("2\n")
+ idx, err := p.SelectOne("Pick one", []string{"a", "b", "c"})
+ if err != nil {
+ t.Fatalf("SelectOne: %v", err)
+ }
+ if idx != 1 {
+ t.Fatalf("idx = %d, want 1", idx)
+ }
+}
+
+func TestSelectOneRepromptsThenSucceeds(t *testing.T) {
+ p, out := newTest("9\nx\n1\n")
+ idx, err := p.SelectOne("Pick one", []string{"a", "b"})
+ if err != nil {
+ t.Fatalf("SelectOne: %v", err)
+ }
+ if idx != 0 {
+ t.Fatalf("idx = %d, want 0", idx)
+ }
+ if !strings.Contains(out.String(), "between 1 and 2") {
+ t.Errorf("expected reprompt message, got: %q", out.String())
+ }
+}
+
+func TestSelectOneEOFReturnsError(t *testing.T) {
+ p, _ := newTest("")
+ if _, err := p.SelectOne("Pick", []string{"a"}); err == nil {
+ t.Fatal("expected error on EOF")
+ }
+}
+
+func TestSelectManyCommaList(t *testing.T) {
+ p, _ := newTest("1,3\n")
+ idxs, err := p.SelectMany("Pick many", []string{"a", "b", "c"}, true)
+ if err != nil {
+ t.Fatalf("SelectMany: %v", err)
+ }
+ if len(idxs) != 2 || idxs[0] != 0 || idxs[1] != 2 {
+ t.Fatalf("idxs = %v, want [0 2]", idxs)
+ }
+}
+
+func TestSelectManyAll(t *testing.T) {
+ p, _ := newTest("all\n")
+ idxs, err := p.SelectMany("Pick many", []string{"a", "b", "c"}, true)
+ if err != nil {
+ t.Fatalf("SelectMany: %v", err)
+ }
+ if len(idxs) != 3 {
+ t.Fatalf("idxs = %v, want all three", idxs)
+ }
+}
+
+func TestSelectManyDedupsAndReprompts(t *testing.T) {
+ p, _ := newTest("5\n2,2,1\n")
+ idxs, err := p.SelectMany("Pick", []string{"a", "b", "c"}, false)
+ if err != nil {
+ t.Fatalf("SelectMany: %v", err)
+ }
+ if len(idxs) != 2 || idxs[0] != 1 || idxs[1] != 0 {
+ t.Fatalf("idxs = %v, want [1 0] (deduped, ordered)", idxs)
+ }
+}
+
+func TestInputDefaultOnEmpty(t *testing.T) {
+ p, _ := newTest("\n")
+ got, err := p.Input("Slug", "acme-support")
+ if err != nil {
+ t.Fatalf("Input: %v", err)
+ }
+ if got != "acme-support" {
+ t.Fatalf("got %q, want default", got)
+ }
+}
+
+func TestInputOverride(t *testing.T) {
+ p, _ := newTest("custom-slug\n")
+ got, err := p.Input("Slug", "acme-support")
+ if err != nil {
+ t.Fatalf("Input: %v", err)
+ }
+ if got != "custom-slug" {
+ t.Fatalf("got %q, want custom-slug", got)
+ }
+}
+
+func TestConfirm(t *testing.T) {
+ cases := map[string]bool{
+ "y\n": true,
+ "yes\n": true,
+ "Y\n": true,
+ "\n": false,
+ "n\n": false,
+ "nope\n": false,
+ }
+ for in, want := range cases {
+ p, _ := newTest(in)
+ got, err := p.Confirm("Proceed?")
+ if err != nil {
+ t.Fatalf("Confirm(%q): %v", in, err)
+ }
+ if got != want {
+ t.Errorf("Confirm(%q) = %v, want %v", in, got, want)
+ }
+ }
+}
diff --git a/internal/sdk/help_center.go b/internal/sdk/help_center.go
index 694c8cd..6149920 100644
--- a/internal/sdk/help_center.go
+++ b/internal/sdk/help_center.go
@@ -1,7 +1,11 @@
package sdk
import (
+ "bytes"
+ "encoding/json"
"fmt"
+ "mime/multipart"
+ "net/http"
"net/url"
"strconv"
"strings"
@@ -165,3 +169,240 @@ func helpCenterArticlesPath(portalSlug, locale, categorySlug string) (string, er
url.PathEscape(categorySlug),
), nil
}
+
+// ---------------------------------------------------------------------------
+// Write API (authoring) — account-scoped, admin token required.
+//
+// Response wrappers differ per endpoint (verified against the Chatwoot
+// controllers/jbuilder views): portal create/update return a BARE portal
+// object, while category and article create/update wrap the record under a
+// "payload" key.
+// ---------------------------------------------------------------------------
+
+// PortalConfigInput is the WRITE shape of a portal's config. Note that
+// allowed_locales is a flat []string on write, even though the read API
+// renders it as an array of objects.
+type PortalConfigInput struct {
+ AllowedLocales []string `json:"allowed_locales,omitempty"`
+ DefaultLocale string `json:"default_locale,omitempty"`
+ Layout string `json:"layout,omitempty"`
+}
+
+// PortalInput is the request body for creating/updating a portal.
+type PortalInput struct {
+ Name string `json:"name,omitempty"`
+ Slug string `json:"slug,omitempty"`
+ Config *PortalConfigInput `json:"config,omitempty"`
+}
+
+// CreatePortal creates a help center portal. The response is a bare portal
+// object (no payload wrapper).
+func (s *HelpCenterService) CreatePortal(req PortalInput) (*HelpCenterPortal, error) {
+ body, err := json.Marshal(map[string]PortalInput{"portal": req})
+ if err != nil {
+ return nil, err
+ }
+
+ var portal HelpCenterPortal
+ if err := s.client.Post("/portals", bytes.NewReader(body), &portal); err != nil {
+ return nil, err
+ }
+ return &portal, nil
+}
+
+// UpdatePortal updates a portal by slug (used to reconcile allowed_locales).
+// The response is a bare portal object.
+func (s *HelpCenterService) UpdatePortal(slug string, req PortalInput) (*HelpCenterPortal, error) {
+ if strings.TrimSpace(slug) == "" {
+ return nil, fmt.Errorf("portal slug is required")
+ }
+
+ body, err := json.Marshal(map[string]PortalInput{"portal": req})
+ if err != nil {
+ return nil, err
+ }
+
+ var portal HelpCenterPortal
+ path := fmt.Sprintf("/portals/%s", url.PathEscape(slug))
+ if err := s.client.Patch(path, bytes.NewReader(body), &portal); err != nil {
+ return nil, err
+ }
+ return &portal, nil
+}
+
+// HelpCenterCategory is a category record as returned by the write API.
+type HelpCenterCategory struct {
+ ID int `json:"id"`
+ Name string `json:"name"`
+ Slug string `json:"slug"`
+ Locale string `json:"locale"`
+ Description string `json:"description"`
+ Position int `json:"position"`
+ AccountID int `json:"account_id"`
+}
+
+type HelpCenterCategoriesResponse struct {
+ Payload []HelpCenterCategory `json:"payload"`
+ Meta map[string]any `json:"meta"`
+}
+
+type categoryEnvelope struct {
+ Payload HelpCenterCategory `json:"payload"`
+}
+
+// CreateCategoryRequest is the request body for creating a category. slug is
+// REQUIRED — unlike articles, the server does not auto-generate it.
+type CreateCategoryRequest struct {
+ Name string `json:"name"`
+ Slug string `json:"slug"`
+ Locale string `json:"locale"`
+ Description string `json:"description,omitempty"`
+ ParentCategoryID int `json:"parent_category_id,omitempty"`
+ AssociatedCategoryID int `json:"associated_category_id,omitempty"`
+ Position int `json:"position,omitempty"`
+}
+
+// ListCategories lists a portal's categories, optionally filtered by locale.
+func (s *HelpCenterService) ListCategories(portalSlug, locale string) (*HelpCenterCategoriesResponse, error) {
+ if strings.TrimSpace(portalSlug) == "" {
+ return nil, fmt.Errorf("portal slug is required")
+ }
+
+ params := url.Values{}
+ if strings.TrimSpace(locale) != "" {
+ params.Set("locale", locale)
+ }
+
+ var resp HelpCenterCategoriesResponse
+ path := fmt.Sprintf("/portals/%s/categories", url.PathEscape(portalSlug))
+ if err := s.client.Get(path, params, &resp); err != nil {
+ return nil, err
+ }
+ return &resp, nil
+}
+
+// CreateCategory creates a category under a portal. Returns the created
+// category (unwrapped from the payload envelope).
+func (s *HelpCenterService) CreateCategory(portalSlug string, req CreateCategoryRequest) (*HelpCenterCategory, error) {
+ if strings.TrimSpace(portalSlug) == "" {
+ return nil, fmt.Errorf("portal slug is required")
+ }
+
+ body, err := json.Marshal(map[string]CreateCategoryRequest{"category": req})
+ if err != nil {
+ return nil, err
+ }
+
+ var env categoryEnvelope
+ path := fmt.Sprintf("/portals/%s/categories", url.PathEscape(portalSlug))
+ if err := s.client.Post(path, bytes.NewReader(body), &env); err != nil {
+ return nil, err
+ }
+ return &env.Payload, nil
+}
+
+type articleEnvelope struct {
+ Payload HelpCenterArticle `json:"payload"`
+}
+
+// ArticleMetaInput is the optional SEO/meta object on an article.
+type ArticleMetaInput struct {
+ Title string `json:"title,omitempty"`
+ Description string `json:"description,omitempty"`
+ Tags []string `json:"tags,omitempty"`
+}
+
+// CreateArticleRequest is the request body for creating/updating an article.
+// title and author_id are required; content is required only when published
+// (imports use draft). slug may be omitted — the server auto-generates it.
+// associated_article_id is honored at create time and flattened to the root.
+type CreateArticleRequest struct {
+ Title string `json:"title,omitempty"`
+ Content string `json:"content,omitempty"`
+ Description string `json:"description,omitempty"`
+ Slug string `json:"slug,omitempty"`
+ Status string `json:"status,omitempty"`
+ Locale string `json:"locale,omitempty"`
+ AuthorID int `json:"author_id,omitempty"`
+ Position int `json:"position,omitempty"`
+ CategoryID int `json:"category_id,omitempty"`
+ AssociatedArticleID int `json:"associated_article_id,omitempty"`
+ Meta *ArticleMetaInput `json:"meta,omitempty"`
+}
+
+// CreateArticle creates an article under a portal. Returns the created article
+// (unwrapped from the payload envelope).
+func (s *HelpCenterService) CreateArticle(portalSlug string, req CreateArticleRequest) (*HelpCenterArticle, error) {
+ if strings.TrimSpace(portalSlug) == "" {
+ return nil, fmt.Errorf("portal slug is required")
+ }
+
+ body, err := json.Marshal(map[string]CreateArticleRequest{"article": req})
+ if err != nil {
+ return nil, err
+ }
+
+ var env articleEnvelope
+ path := fmt.Sprintf("/portals/%s/articles", url.PathEscape(portalSlug))
+ if err := s.client.Post(path, bytes.NewReader(body), &env); err != nil {
+ return nil, err
+ }
+ return &env.Payload, nil
+}
+
+// UpdateArticle updates an article by id (used for re-link/repair). Returns the
+// updated article.
+func (s *HelpCenterService) UpdateArticle(portalSlug string, id int, req CreateArticleRequest) (*HelpCenterArticle, error) {
+ if strings.TrimSpace(portalSlug) == "" {
+ return nil, fmt.Errorf("portal slug is required")
+ }
+
+ body, err := json.Marshal(map[string]CreateArticleRequest{"article": req})
+ if err != nil {
+ return nil, err
+ }
+
+ var env articleEnvelope
+ path := fmt.Sprintf("/portals/%s/articles/%d", url.PathEscape(portalSlug), id)
+ if err := s.client.Patch(path, bytes.NewReader(body), &env); err != nil {
+ return nil, err
+ }
+ return &env.Payload, nil
+}
+
+// UploadResult is the response from the /upload endpoint. blob_id is an
+// ActiveStorage signed_id (a string).
+type UploadResult struct {
+ FileURL string `json:"file_url"`
+ BlobID string `json:"blob_id"`
+}
+
+// UploadImageExternalURL uploads an image by asking the server to fetch a
+// remote URL (via SafeFetch). Returns the hosted file_url to embed in article
+// content. Uses a multipart form with a single external_url field.
+func (s *HelpCenterService) UploadImageExternalURL(externalURL string) (*UploadResult, error) {
+ if strings.TrimSpace(externalURL) == "" {
+ return nil, fmt.Errorf("external_url is required")
+ }
+
+ var buf bytes.Buffer
+ w := multipart.NewWriter(&buf)
+ if err := w.WriteField("external_url", externalURL); err != nil {
+ return nil, err
+ }
+ if err := w.Close(); err != nil {
+ return nil, err
+ }
+
+ headers := http.Header{"Content-Type": {w.FormDataContentType()}}
+ resp, err := s.client.RequestRaw(http.MethodPost, "/upload", &buf, true, headers)
+ if err != nil {
+ return nil, err
+ }
+
+ var result UploadResult
+ if err := json.Unmarshal(resp.Body, &result); err != nil {
+ return nil, fmt.Errorf("failed to decode upload response: %w", err)
+ }
+ return &result, nil
+}
diff --git a/internal/sdk/help_center_write_test.go b/internal/sdk/help_center_write_test.go
new file mode 100644
index 0000000..658eee3
--- /dev/null
+++ b/internal/sdk/help_center_write_test.go
@@ -0,0 +1,253 @@
+package sdk
+
+import (
+ "encoding/json"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+)
+
+// decodeBody decodes a request's JSON body into a generic map for assertions.
+func decodeBody(t *testing.T, r *http.Request) map[string]any {
+ t.Helper()
+ raw, err := io.ReadAll(r.Body)
+ if err != nil {
+ t.Fatalf("read body: %v", err)
+ }
+ var m map[string]any
+ if err := json.Unmarshal(raw, &m); err != nil {
+ t.Fatalf("decode body %q: %v", string(raw), err)
+ }
+ return m
+}
+
+func TestCreatePortalSendsConfigAndDecodesBareResponse(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost || r.URL.Path != "/api/v1/accounts/9/portals" {
+ http.Error(w, "unexpected: "+r.Method+" "+r.URL.Path, http.StatusNotFound)
+ return
+ }
+ body := decodeBody(t, r)
+ portal, ok := body["portal"].(map[string]any)
+ if !ok {
+ t.Fatalf("body not wrapped under portal: %#v", body)
+ }
+ if portal["slug"] != "acme-support" {
+ t.Errorf("slug = %v, want acme-support", portal["slug"])
+ }
+ cfg, ok := portal["config"].(map[string]any)
+ if !ok {
+ t.Fatalf("config missing: %#v", portal)
+ }
+ locales, ok := cfg["allowed_locales"].([]any)
+ if !ok || len(locales) != 2 || locales[0] != "en" || locales[1] != "fr" {
+ t.Errorf("allowed_locales = %#v, want [en fr] as strings", cfg["allowed_locales"])
+ }
+
+ w.Header().Set("Content-Type", "application/json")
+ // Bare portal object — NO payload wrapper.
+ _, _ = w.Write([]byte(`{"id": 7, "name": "Acme Support", "slug": "acme-support"}`))
+ }))
+ t.Cleanup(server.Close)
+
+ client := NewClient(server.URL, "test-token", 9, WithHTTPClient(server.Client()))
+ portal, err := client.HelpCenter().CreatePortal(PortalInput{
+ Name: "Acme Support",
+ Slug: "acme-support",
+ Config: &PortalConfigInput{
+ AllowedLocales: []string{"en", "fr"},
+ DefaultLocale: "en",
+ },
+ })
+ if err != nil {
+ t.Fatalf("CreatePortal: %v", err)
+ }
+ if portal.ID != 7 || portal.Slug != "acme-support" {
+ t.Fatalf("unexpected portal: %#v", portal)
+ }
+}
+
+func TestUpdatePortalPatchesAllowedLocales(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPatch || r.URL.Path != "/api/v1/accounts/9/portals/acme-support" {
+ http.Error(w, "unexpected: "+r.Method+" "+r.URL.Path, http.StatusNotFound)
+ return
+ }
+ body := decodeBody(t, r)
+ cfg := body["portal"].(map[string]any)["config"].(map[string]any)
+ locales := cfg["allowed_locales"].([]any)
+ if len(locales) != 3 {
+ t.Errorf("allowed_locales len = %d, want 3", len(locales))
+ }
+
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"id": 7, "slug": "acme-support"}`))
+ }))
+ t.Cleanup(server.Close)
+
+ client := NewClient(server.URL, "test-token", 9, WithHTTPClient(server.Client()))
+ if _, err := client.HelpCenter().UpdatePortal("acme-support", PortalInput{
+ Config: &PortalConfigInput{AllowedLocales: []string{"en", "fr", "de"}},
+ }); err != nil {
+ t.Fatalf("UpdatePortal: %v", err)
+ }
+}
+
+func TestCreateCategorySendsSlugAndLinksAndUnwrapsPayload(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost || r.URL.Path != "/api/v1/accounts/9/portals/acme-support/categories" {
+ http.Error(w, "unexpected: "+r.Method+" "+r.URL.Path, http.StatusNotFound)
+ return
+ }
+ cat := decodeBody(t, r)["category"].(map[string]any)
+ if cat["slug"] == nil || cat["slug"] == "" {
+ t.Errorf("slug must be present, got %#v", cat["slug"])
+ }
+ if cat["locale"] != "fr" {
+ t.Errorf("locale = %v, want fr", cat["locale"])
+ }
+ if cat["associated_category_id"] != float64(11) {
+ t.Errorf("associated_category_id = %v, want 11", cat["associated_category_id"])
+ }
+ if cat["parent_category_id"] != float64(5) {
+ t.Errorf("parent_category_id = %v, want 5", cat["parent_category_id"])
+ }
+
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"payload": {"id": 21, "slug": "getting-started", "locale": "fr"}}`))
+ }))
+ t.Cleanup(server.Close)
+
+ client := NewClient(server.URL, "test-token", 9, WithHTTPClient(server.Client()))
+ cat, err := client.HelpCenter().CreateCategory("acme-support", CreateCategoryRequest{
+ Name: "Commencer",
+ Slug: "getting-started",
+ Locale: "fr",
+ ParentCategoryID: 5,
+ AssociatedCategoryID: 11,
+ })
+ if err != nil {
+ t.Fatalf("CreateCategory: %v", err)
+ }
+ if cat.ID != 21 || cat.Locale != "fr" {
+ t.Fatalf("unexpected category: %#v", cat)
+ }
+}
+
+func TestListCategoriesPassesLocaleQuery(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/api/v1/accounts/9/portals/acme-support/categories" {
+ http.Error(w, "unexpected path: "+r.URL.Path, http.StatusNotFound)
+ return
+ }
+ if got := r.URL.Query().Get("locale"); got != "en" {
+ t.Errorf("locale = %q, want en", got)
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"payload": [{"id": 3, "slug": "faq", "locale": "en"}], "meta": {"categories_count": 1}}`))
+ }))
+ t.Cleanup(server.Close)
+
+ client := NewClient(server.URL, "test-token", 9, WithHTTPClient(server.Client()))
+ resp, err := client.HelpCenter().ListCategories("acme-support", "en")
+ if err != nil {
+ t.Fatalf("ListCategories: %v", err)
+ }
+ if len(resp.Payload) != 1 || resp.Payload[0].Slug != "faq" {
+ t.Fatalf("unexpected categories: %#v", resp)
+ }
+}
+
+func TestCreateArticleSendsLinkLocaleStatusAndUnwrapsPayload(t *testing.T) {
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost || r.URL.Path != "/api/v1/accounts/9/portals/acme-support/articles" {
+ http.Error(w, "unexpected: "+r.Method+" "+r.URL.Path, http.StatusNotFound)
+ return
+ }
+ art := decodeBody(t, r)["article"].(map[string]any)
+ if art["status"] != "draft" {
+ t.Errorf("status = %v, want draft", art["status"])
+ }
+ if art["locale"] != "fr" {
+ t.Errorf("locale = %v, want fr", art["locale"])
+ }
+ if art["associated_article_id"] != float64(100) {
+ t.Errorf("associated_article_id = %v, want 100", art["associated_article_id"])
+ }
+ if art["category_id"] != float64(21) {
+ t.Errorf("category_id = %v, want 21", art["category_id"])
+ }
+ if art["author_id"] != float64(2) {
+ t.Errorf("author_id = %v, want 2", art["author_id"])
+ }
+
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"payload": {"id": 101, "title": "Configurer SSO", "status": "draft"}}`))
+ }))
+ t.Cleanup(server.Close)
+
+ client := NewClient(server.URL, "test-token", 9, WithHTTPClient(server.Client()))
+ art, err := client.HelpCenter().CreateArticle("acme-support", CreateArticleRequest{
+ Title: "Configurer SSO",
+ Content: "...
", + Status: "draft", + Locale: "fr", + AuthorID: 2, + CategoryID: 21, + AssociatedArticleID: 100, + }) + if err != nil { + t.Fatalf("CreateArticle: %v", err) + } + if art.ID != 101 || art.Status != "draft" { + t.Fatalf("unexpected article: %#v", art) + } +} + +func TestUpdateArticlePatchesByID(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPatch || r.URL.Path != "/api/v1/accounts/9/portals/acme-support/articles/101" { + http.Error(w, "unexpected: "+r.Method+" "+r.URL.Path, http.StatusNotFound) + return + } + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"payload": {"id": 101, "title": "Configurer SSO"}}`)) + })) + t.Cleanup(server.Close) + + client := NewClient(server.URL, "test-token", 9, WithHTTPClient(server.Client())) + if _, err := client.HelpCenter().UpdateArticle("acme-support", 101, CreateArticleRequest{ + AssociatedArticleID: 100, + }); err != nil { + t.Fatalf("UpdateArticle: %v", err) + } +} + +func TestUploadImageExternalURLSendsMultipartField(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPost || r.URL.Path != "/api/v1/accounts/9/upload" { + http.Error(w, "unexpected: "+r.Method+" "+r.URL.Path, http.StatusNotFound) + return + } + if err := r.ParseMultipartForm(1 << 20); err != nil { + t.Fatalf("ParseMultipartForm: %v", err) + } + if got := r.FormValue("external_url"); got != "https://cdn.intercom.io/img.png" { + t.Errorf("external_url = %q", got) + } + + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"file_url": "https://app/rails/active_storage/blobs/x/img.png", "blob_id": "signed-abc"}`)) + })) + t.Cleanup(server.Close) + + client := NewClient(server.URL, "test-token", 9, WithHTTPClient(server.Client())) + res, err := client.HelpCenter().UploadImageExternalURL("https://cdn.intercom.io/img.png") + if err != nil { + t.Fatalf("UploadImageExternalURL: %v", err) + } + if res.BlobID != "signed-abc" || res.FileURL == "" { + t.Fatalf("unexpected upload result: %#v", res) + } +}