feat: add Base table copy shortcuts

internal/errclass/codemeta_base.go

@@ -0,0 +1,35 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import "github.com/larksuite/cli/errs"
+
+var baseCodeMeta = map[int]CodeMeta{
+	// Copy Table domain errors (technical design chapter 18.2).
+	800020304: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},
+	800010102: {Category: errs.CategoryValidation, Subtype: errs.SubtypeFailedPrecondition},
+	800080105: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},
+	800040819: {Category: errs.CategoryAPI, Subtype: errs.SubtypeConflict},
+	800070003: {Category: errs.CategoryAPI, Subtype: errs.SubtypeUnknown},
+	800100112: {Category: errs.CategoryInternal, Subtype: errs.SubtypeUnknown},
+	800100113: {Category: errs.CategoryInternal, Subtype: errs.SubtypeUnknown},
+	800040114: {Category: errs.CategoryAPI, Subtype: errs.SubtypeConflict, Retryable: true},
+	800070115: {Category: errs.CategoryAPI, Subtype: errs.SubtypeUnknown},
+	800010109: {Category: errs.CategoryValidation, Subtype: errs.SubtypeInvalidArgument},
+	800030110: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},
+	800070111: {Category: errs.CategoryAPI, Subtype: errs.SubtypeUnknown},
+
+	// Shared RPC errors used by Copy Table (technical design chapter 18.3).
+	800040802: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},
+	800040803: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},
+	800020812: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},
+	800040832: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},
+	800040817: {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},
+	800080821: {Category: errs.CategoryPolicy, Subtype: errs.SubtypeAccessDenied},
+	800070831: {Category: errs.CategoryAPI, Subtype: errs.SubtypeUnknown},
+}
+
+func init() {
+	mergeCodeMeta(baseCodeMeta, "base")
+}

internal/errclass/codemeta_base_test.go

@@ -0,0 +1,51 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package errclass
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+func TestLookupCodeMetaBaseTableCopyCodes(t *testing.T) {
+	tests := []struct {
+		code      int
+		category  errs.Category
+		subtype   errs.Subtype
+		retryable bool
+	}{
+		// Copy Table domain errors documented in chapter 18.2.
+		{code: 800020304, category: errs.CategoryAuthorization, subtype: errs.SubtypePermissionDenied},
+		{code: 800010102, category: errs.CategoryValidation, subtype: errs.SubtypeFailedPrecondition},
+		{code: 800080105, category: errs.CategoryAPI, subtype: errs.SubtypeQuotaExceeded},
+		{code: 800040819, category: errs.CategoryAPI, subtype: errs.SubtypeConflict},
+		{code: 800070003, category: errs.CategoryAPI, subtype: errs.SubtypeUnknown},
+		{code: 800100112, category: errs.CategoryInternal, subtype: errs.SubtypeUnknown},
+		{code: 800100113, category: errs.CategoryInternal, subtype: errs.SubtypeUnknown},
+		{code: 800040114, category: errs.CategoryAPI, subtype: errs.SubtypeConflict, retryable: true},
+		{code: 800070115, category: errs.CategoryAPI, subtype: errs.SubtypeUnknown},
+		{code: 800010109, category: errs.CategoryValidation, subtype: errs.SubtypeInvalidArgument},
+		{code: 800030110, category: errs.CategoryAPI, subtype: errs.SubtypeNotFound},
+		{code: 800070111, category: errs.CategoryAPI, subtype: errs.SubtypeUnknown},
+
+		// Shared RPC errors used by Copy Table, documented in chapter 18.3.
+		{code: 800040802, category: errs.CategoryAPI, subtype: errs.SubtypeQuotaExceeded},
+		{code: 800040803, category: errs.CategoryAPI, subtype: errs.SubtypeQuotaExceeded},
+		{code: 800020812, category: errs.CategoryAuthorization, subtype: errs.SubtypePermissionDenied},
+		{code: 800040832, category: errs.CategoryAPI, subtype: errs.SubtypeQuotaExceeded},
+		{code: 800040817, category: errs.CategoryAPI, subtype: errs.SubtypeQuotaExceeded},
+		{code: 800080821, category: errs.CategoryPolicy, subtype: errs.SubtypeAccessDenied},
+		{code: 800070831, category: errs.CategoryAPI, subtype: errs.SubtypeUnknown},
+	}
+	for _, test := range tests {
+		t.Run(fmt.Sprint(test.code), func(t *testing.T) {
+			meta, ok := LookupCodeMeta(test.code)
+			if !ok || meta.Category != test.category || meta.Subtype != test.subtype || meta.Retryable != test.retryable {
+				t.Fatalf("LookupCodeMeta(%d) = %#v, %v", test.code, meta, ok)
+			}
+		})
+	}
+}

internal/httpmock/registry.go

@@ -23,6 +23,7 @@ type Stub struct {
 	RawBody     []byte      // raw bytes (takes precedence over Body when non-nil)
 	ContentType string      // override Content-Type header (default: application/json)
 	Headers     http.Header // optional full response headers (takes precedence over ContentType)
+	Error       error       // optional transport error returned after OnMatch
 	matched     bool
 
 	// BodyFilter (optional): match only when the captured request body satisfies
@@ -93,6 +94,9 @@ func (r *Registry) RoundTrip(req *http.Request) (*http.Response, error) {
 		if matched.OnMatch != nil {
 			matched.OnMatch(req)
 		}
+		if matched.Error != nil {
+			return nil, matched.Error
+		}
 		resp, err := stubResponse(matched)
 		if err != nil {
 			return nil, fmt.Errorf("httpmock: stub %s %s: %w", matched.Method, matched.URL, err)

internal/httpmock/registry_test.go

@@ -4,6 +4,7 @@
 package httpmock
 
 import (
+	"errors"
 	"io"
 	"net/http"
 	"testing"
@@ -112,3 +113,21 @@ func TestRegistry_CustomStatus(t *testing.T) {
 		t.Errorf("want status 500, got %d", resp.StatusCode)
 	}
 }
+
+func TestRegistry_TransportError(t *testing.T) {
+	wantErr := errors.New("connection reset")
+	reg := &Registry{}
+	reg.Register(&Stub{
+		Method: "POST",
+		URL:    "/transport-error",
+		Error:  wantErr,
+	})
+
+	client := NewClient(reg)
+	req, _ := http.NewRequest("POST", "https://example.com/transport-error", nil)
+	_, err := client.Do(req)
+	if !errors.Is(err, wantErr) {
+		t.Fatalf("error = %v, want transport error %v", err, wantErr)
+	}
+	reg.Verify(t)
+}

shortcuts/base/base_shortcuts_test.go

@@ -161,7 +161,7 @@ func TestShortcutsCatalog(t *testing.T) {
 	want := []string{
 		"+url-resolve", "+title-resolve",
 		"+base-block-list", "+base-block-create", "+base-block-move", "+base-block-rename", "+base-block-delete",
-		"+table-list", "+table-get", "+table-create", "+table-update", "+table-delete",
+		"+table-list", "+table-get", "+table-create", "+table-update", "+table-delete", "+table-copy", "+table-copy-status",
 		"+field-list", "+field-get", "+field-create", "+field-update", "+field-delete", "+field-search-options",
 		"+view-list", "+view-get", "+view-create", "+view-delete", "+view-get-filter", "+view-set-filter", "+view-get-visible-fields", "+view-set-visible-fields", "+view-get-group", "+view-set-group", "+view-get-sort", "+view-set-sort", "+view-get-timebar", "+view-set-timebar", "+view-get-card", "+view-set-card", "+view-rename",
 		"+record-list", "+record-search", "+record-get", "+record-upsert", "+record-batch-create", "+record-batch-update", "+record-share-link-create", "+record-upload-attachment", "+record-download-attachment", "+record-remove-attachment", "+record-delete",

shortcuts/base/helpers.go

@@ -5,6 +5,7 @@ package base
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -386,6 +387,10 @@ func baseV3Path(parts ...string) string {
 }
 
 func baseV3Raw(runtime *common.RuntimeContext, method, path string, params map[string]interface{}, data interface{}) (map[string]interface{}, error) {
+	return baseV3RawContext(runtime.Ctx(), runtime, method, path, params, data)
+}
+
+func baseV3RawContext(ctx context.Context, runtime *common.RuntimeContext, method, path string, params map[string]interface{}, data interface{}) (map[string]interface{}, error) {
 	queryParams := make(larkcore.QueryParams)
 	for k, v := range params {
 		switch val := v.(type) {
@@ -409,7 +414,7 @@ func baseV3Raw(runtime *common.RuntimeContext, method, path string, params map[s
 	}
 	h := make(http.Header)
 	h.Set("X-App-Id", runtime.Config.AppID)
-	resp, err := runtime.DoAPI(req, larkcore.WithHeaders(h))
+	resp, err := runtime.DoAPIWithContext(ctx, req, larkcore.WithHeaders(h))
 	if err != nil {
 		return nil, baseAPIBoundaryError(err, "API call failed")
 	}
@@ -504,6 +509,11 @@ func baseV3Call(runtime *common.RuntimeContext, method, path string, params map[
 	return handleBaseAPIResult(result, err, "API call failed")
 }
 
+func baseV3CallContext(ctx context.Context, runtime *common.RuntimeContext, method, path string, params map[string]interface{}, data interface{}) (map[string]interface{}, error) {
+	result, err := baseV3RawContext(ctx, runtime, method, path, params, data)
+	return handleBaseAPIResult(result, err, "API call failed")
+}
+
 func baseV3CallAny(runtime *common.RuntimeContext, method, path string, params map[string]interface{}, data interface{}) (interface{}, error) {
 	result, err := baseV3Raw(runtime, method, path, params, data)
 	return handleBaseAPIResultAny(result, err, "API call failed")

shortcuts/base/shortcuts.go

@@ -20,6 +20,8 @@ func Shortcuts() []common.Shortcut {
 		BaseTableCreate,
 		BaseTableUpdate,
 		BaseTableDelete,
+		BaseTableCopy,
+		BaseTableCopyStatus,
 		BaseFieldList,
 		BaseFieldGet,
 		BaseFieldCreate,

shortcuts/base/table_copy.go

@@ -0,0 +1,119 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+const (
+	tableCopyRangeSchema = "schema"
+	tableCopyRangeAll    = "all"
+	tableCopyScope       = "base:table:create"
+	tableCopyTimeoutMax  = 30 * time.Minute
+	tableCopyTaskIDMax   = 1024
+)
+
+var BaseTableCopy = common.Shortcut{
+	Service:     "base",
+	Command:     "+table-copy",
+	Description: "Copy a table by ID or name; structure only by default",
+	Risk:        "write",
+	Scopes:      []string{tableCopyScope},
+	AuthTypes:   authTypes(),
+	Flags: []common.Flag{
+		baseTokenFlag(true),
+		tableRefFlag(true),
+		{Name: "name", Desc: "target table name", Required: true},
+		{Name: "range", Default: tableCopyRangeSchema, Desc: "copy range; defaults to schema, use all only to include records", Enum: []string{tableCopyRangeSchema, tableCopyRangeAll}},
+		{Name: "wait", Type: "bool", Desc: "wait for an all-range copy task to finish"},
+	},
+	Tips: []string{
+		`Example: lark-cli base +table-copy --base-token <base_token> --table-id "Tasks" --name "Tasks copy"`,
+		"table-id accepts a table ID or name in the current Base.",
+		"The default copies schema only; use --range all only when records must also be copied.",
+		"Use --wait with --range all to wait locally; otherwise continue with the returned next_command.",
+	},
+	DryRun: dryRunTableCopy,
+	PostMount: func(cmd *cobra.Command) {
+		cmd.Flags().Duration("timeout", 5*time.Minute, "maximum time to wait for an asynchronous copy task (max 30m)")
+	},
+	Validate: validateTableCopy,
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return executeTableCopy(ctx, runtime)
+	},
+}
+
+var BaseTableCopyStatus = common.Shortcut{
+	Service:     "base",
+	Command:     "+table-copy-status",
+	Description: "Get one table copy task status",
+	Risk:        "read",
+	Scopes:      []string{tableCopyScope},
+	AuthTypes:   authTypes(),
+	Flags: []common.Flag{
+		baseTokenFlag(true),
+		{Name: "task-id", Desc: "opaque table copy task ID", Required: true},
+	},
+	Tips: []string{
+		"Use the opaque task_id returned by base +table-copy; this command queries status once.",
+		"If state is init or process, run the returned next_command later.",
+	},
+	DryRun: dryRunTableCopyStatus,
+	Validate: func(_ context.Context, runtime *common.RuntimeContext) error {
+		taskID := runtime.Str("task-id")
+		if strings.TrimSpace(taskID) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--task-id cannot be blank").WithParam("--task-id")
+		}
+		if len(taskID) > tableCopyTaskIDMax {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--task-id must not exceed %d bytes", tableCopyTaskIDMax).WithParam("--task-id")
+		}
+		return nil
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return executeTableCopyStatus(ctx, runtime)
+	},
+}
+
+func validateTableCopy(_ context.Context, runtime *common.RuntimeContext) error {
+	if strings.TrimSpace(runtime.Str("table-id")) == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--table-id cannot be blank").WithParam("--table-id")
+	}
+	if strings.TrimSpace(runtime.Str("name")) == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--name cannot be blank").WithParam("--name")
+	}
+
+	rangeValue := runtime.Str("range")
+	wait := runtime.Bool("wait")
+	timeoutChanged := runtime.Changed("timeout")
+	if rangeValue == tableCopyRangeSchema {
+		if wait {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--wait requires --range all").WithParam("--wait")
+		}
+		if timeoutChanged {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--timeout requires --range all and --wait").WithParam("--timeout")
+		}
+	}
+	if timeoutChanged && !wait {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--timeout requires --wait").WithParam("--timeout")
+	}
+	timeout, err := tableCopyTimeout(runtime)
+	if err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --timeout: %v", err).WithParam("--timeout").WithCause(err)
+	}
+	if wait && (timeout <= 0 || timeout > tableCopyTimeoutMax) {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--timeout must be greater than 0 and at most 30m").WithParam("--timeout")
+	}
+	return nil
+}
+
+func tableCopyTimeout(runtime *common.RuntimeContext) (time.Duration, error) {
+	return runtime.Cmd.Flags().GetDuration("timeout")
+}