feat: add note domain transcript support

Author: Ren1104

shortcuts/note/note.go

@@ -0,0 +1,199 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package note owns the Note domain: querying note detail and the unified
+// transcript by a known note_id. The vc domain locates a
+// note_id from meeting context and delegates note-detail parsing here, so the
+// parsing logic lives in exactly one place.
+package note
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// NoNoteReadPermissionCode is returned when the caller lacks read permission
+// for the requested note.
+const NoNoteReadPermissionCode = 121005
+
+// artifact_type enum from the note detail API.
+const (
+	artifactTypeMainDoc  = 1 // main note document
+	artifactTypeVerbatim = 2 // verbatim transcript
+)
+
+// note_display_type enum (i32) from the note detail API. Surfaced to callers as
+// a stable string so Agents route on a name, not a magic number.
+const (
+	displayTypeNormal  = 1
+	displayTypeUnified = 2
+)
+
+// Detail is the parsed note detail shared by `note +detail` and `vc +notes`.
+type Detail struct {
+	NoteID           string
+	CreatorID        string
+	CreateTime       string
+	DisplayType      string // unknown | normal | unified
+	NoteDocToken     string
+	VerbatimDocToken string
+	SharedDocTokens  []string
+}
+
+// FetchDetail queries GET /open-apis/vc/v1/notes/{note_id} and parses the note
+// object. The raw API error is returned untouched so callers map the
+// no-permission case to their own user-facing message.
+func FetchDetail(_ context.Context, runtime *common.RuntimeContext, noteID string) (*Detail, error) {
+	data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/vc/v1/notes/%s", validate.EncodePathSegment(noteID)), nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	noteObj, _ := data["note"].(map[string]any)
+	if noteObj == nil {
+		return nil, output.ErrAPI(0, "note detail is empty", nil)
+	}
+	noteDoc, verbatimDoc := extractArtifactTokens(common.GetSlice(noteObj, "artifacts"))
+	return &Detail{
+		NoteID:           noteID,
+		CreatorID:        common.GetString(noteObj, "creator_id"),
+		CreateTime:       common.FormatTime(noteObj["create_time"]),
+		DisplayType:      displayTypeString(displayTypeValue(noteObj)),
+		NoteDocToken:     noteDoc,
+		VerbatimDocToken: verbatimDoc,
+		SharedDocTokens:  extractDocTokens(common.GetSlice(noteObj, "references")),
+	}, nil
+}
+
+// ToMap renders the detail as the field map consumed by `vc +notes`, keeping
+// the historical key set (shared_doc_tokens omitted when empty) and adding the
+// note_id / note_display_type fields.
+func (d *Detail) ToMap() map[string]any {
+	m := map[string]any{
+		"note_id":            d.NoteID,
+		"note_display_type":  d.DisplayType,
+		"creator_id":         d.CreatorID,
+		"create_time":        d.CreateTime,
+		"note_doc_token":     d.NoteDocToken,
+		"verbatim_doc_token": d.VerbatimDocToken,
+	}
+	if len(d.SharedDocTokens) > 0 {
+		m["shared_doc_tokens"] = d.SharedDocTokens
+	}
+	return m
+}
+
+// displayTypeValue reads the display-type field, tolerating either the
+// documented note_display_type key or a bare display_type fallback.
+func displayTypeValue(note map[string]any) any {
+	if v, ok := note["note_display_type"]; ok {
+		return v
+	}
+	return note["display_type"]
+}
+
+func displayTypeString(v any) string {
+	switch parseLooseInt(v) {
+	case displayTypeNormal:
+		return "normal"
+	case displayTypeUnified:
+		return "unified"
+	default:
+		return "unknown"
+	}
+}
+
+// extractArtifactTokens picks main-doc and verbatim-doc tokens from artifacts.
+func extractArtifactTokens(artifacts []any) (noteDoc, verbatimDoc string) {
+	for _, a := range artifacts {
+		artifact, _ := a.(map[string]any)
+		if artifact == nil {
+			continue
+		}
+		docToken, _ := artifact["doc_token"].(string)
+		switch parseLooseInt(artifact["artifact_type"]) {
+		case artifactTypeMainDoc:
+			noteDoc = docToken
+		case artifactTypeVerbatim:
+			verbatimDoc = docToken
+		}
+	}
+	return
+}
+
+// extractDocTokens collects doc_token values from a list of reference objects.
+func extractDocTokens(refs []any) []string {
+	var tokens []string
+	for _, s := range refs {
+		source, _ := s.(map[string]any)
+		if source == nil {
+			continue
+		}
+		if docToken, _ := source["doc_token"].(string); docToken != "" {
+			tokens = append(tokens, docToken)
+		}
+	}
+	return tokens
+}
+
+// parseLooseInt extracts an int from the varying JSON number representations
+// DoAPIJSON may yield (json.Number, float64, or int).
+func parseLooseInt(v any) int {
+	switch n := v.(type) {
+	case json.Number:
+		i, _ := n.Int64()
+		return int(i)
+	case float64:
+		return int(n)
+	case int:
+		return n
+	default:
+		return 0
+	}
+}
+
+// parseLooseCursorID extracts a positive cursor as a string. String cursors are
+// preferred because large JSON numbers lose precision when decoded into any.
+func parseLooseCursorID(v any) (string, bool) {
+	switch n := v.(type) {
+	case string:
+		s := strings.TrimSpace(n)
+		if s == "" || s == "0" {
+			return "", false
+		}
+		return s, true
+	case json.Number:
+		i, err := n.Int64()
+		if err != nil || i <= 0 {
+			return "", false
+		}
+		return strconv.FormatInt(i, 10), true
+	case float64:
+		// encoding/json decodes numbers in map[string]any as float64. Accept
+		// only values that can round-trip safely as an integer cursor.
+		const maxSafeJSONInteger = 1<<53 - 1
+		if n <= 0 || n != float64(int64(n)) || n > maxSafeJSONInteger {
+			return "", false
+		}
+		return strconv.FormatInt(int64(n), 10), true
+	case int64:
+		if n <= 0 {
+			return "", false
+		}
+		return strconv.FormatInt(n, 10), true
+	case int:
+		if n <= 0 {
+			return "", false
+		}
+		return strconv.Itoa(n), true
+	default:
+		return "", false
+	}
+}

shortcuts/note/note_detail.go

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// note +detail — get note metadata and document tokens by a known note_id.
+
+package note
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// NoteDetail queries note metadata, display type and document tokens by note_id.
+var NoteDetail = common.Shortcut{
+	Service:     "note",
+	Command:     "+detail",
+	Description: "Get note detail (display type, document tokens) by note_id",
+	Risk:        "read",
+	Scopes:      []string{"vc:note:read"},
+	AuthTypes:   []string{"user"},
+	Flags: []common.Flag{
+		{Name: "note-id", Desc: "note ID", Required: true},
+	},
+	Validate: func(_ context.Context, runtime *common.RuntimeContext) error {
+		noteID := strings.TrimSpace(runtime.Str("note-id"))
+		if noteID == "" {
+			return output.ErrValidation("--note-id is required")
+		}
+		if err := validate.ResourceName(noteID, "--note-id"); err != nil {
+			return output.ErrValidation("%s", err)
+		}
+		return nil
+	},
+	DryRun: func(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		noteID := strings.TrimSpace(runtime.Str("note-id"))
+		return common.NewDryRunAPI().
+			GET(fmt.Sprintf("/open-apis/vc/v1/notes/%s", validate.EncodePathSegment(noteID)))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		noteID := strings.TrimSpace(runtime.Str("note-id"))
+		detail, err := FetchDetail(ctx, runtime, noteID)
+		if err != nil {
+			return mapNoteError(err)
+		}
+		runtime.OutFormat(map[string]any{"note": detail.ToMap()}, nil, nil)
+		return nil
+	},
+}
+
+// mapNoteError surfaces the no-permission case explicitly and passes through
+// any other API error unchanged.
+func mapNoteError(err error) error {
+	var exitErr *output.ExitError
+	if errors.As(err, &exitErr) && exitErr.Detail != nil && exitErr.Detail.Code == NoNoteReadPermissionCode {
+		return output.ErrAPI(NoNoteReadPermissionCode, "no read permission for this note", nil)
+	}
+	return err
+}

shortcuts/note/note_test.go

@@ -0,0 +1,103 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package note
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// These tests were relocated from shortcuts/vc/vc_notes_test.go together with
+// the note-detail parsing helpers they cover.
+
+func TestParseLooseInt(t *testing.T) {
+	tests := []struct {
+		input any
+		want  int
+	}{
+		{float64(1), 1},
+		{float64(2), 2},
+		{json.Number("3"), 3},
+		{"unknown", 0},
+		{nil, 0},
+	}
+	for _, tt := range tests {
+		got := parseLooseInt(tt.input)
+		if got != tt.want {
+			t.Errorf("parseLooseInt(%v) = %d, want %d", tt.input, got, tt.want)
+		}
+	}
+}
+
+func TestParseLooseCursorID(t *testing.T) {
+	tests := []struct {
+		name string
+		in   any
+		want string
+		ok   bool
+	}{
+		{name: "string", in: "7648924766078847940", want: "7648924766078847940", ok: true},
+		{name: "trim string", in: " 123 ", want: "123", ok: true},
+		{name: "empty string", in: "", ok: false},
+		{name: "zero string", in: "0", ok: false},
+		{name: "json number", in: json.Number("123"), want: "123", ok: true},
+		{name: "float safe integer", in: float64(123), want: "123", ok: true},
+		{name: "float unsafe integer", in: float64(1<<53 + 1), ok: false},
+		{name: "float fractional", in: float64(1.5), ok: false},
+		{name: "negative", in: -1, ok: false},
+		{name: "nil", in: nil, ok: false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := parseLooseCursorID(tt.in)
+			if got != tt.want || ok != tt.ok {
+				t.Fatalf("parseLooseCursorID(%v) = (%q, %v), want (%q, %v)", tt.in, got, ok, tt.want, tt.ok)
+			}
+		})
+	}
+}
+
+func TestExtractArtifactTokens(t *testing.T) {
+	artifacts := []any{
+		map[string]any{"doc_token": "main_doc", "artifact_type": float64(1)},
+		map[string]any{"doc_token": "verbatim_doc", "artifact_type": float64(2)},
+		map[string]any{"doc_token": "unknown_doc", "artifact_type": float64(99)},
+		nil,
+	}
+	noteDoc, verbatimDoc := extractArtifactTokens(artifacts)
+	if noteDoc != "main_doc" {
+		t.Errorf("noteDoc = %q, want %q", noteDoc, "main_doc")
+	}
+	if verbatimDoc != "verbatim_doc" {
+		t.Errorf("verbatimDoc = %q, want %q", verbatimDoc, "verbatim_doc")
+	}
+}
+
+func TestExtractArtifactTokens_Empty(t *testing.T) {
+	noteDoc, verbatimDoc := extractArtifactTokens(nil)
+	if noteDoc != "" || verbatimDoc != "" {
+		t.Errorf("expected empty tokens for nil input, got %q, %q", noteDoc, verbatimDoc)
+	}
+}
+
+func TestExtractDocTokens(t *testing.T) {
+	refs := []any{
+		map[string]any{"doc_token": "shared1"},
+		map[string]any{"doc_token": "shared2"},
+		map[string]any{"doc_token": ""},
+		map[string]any{},
+		nil,
+	}
+	tokens := extractDocTokens(refs)
+	if len(tokens) != 2 || tokens[0] != "shared1" || tokens[1] != "shared2" {
+		t.Errorf("extractDocTokens = %v, want [shared1 shared2]", tokens)
+	}
+}
+
+func TestExtractDocTokens_Empty(t *testing.T) {
+	tokens := extractDocTokens(nil)
+	if tokens != nil {
+		t.Errorf("expected nil for nil input, got %v", tokens)
+	}
+}