@shipfox/client-secrets 5.0.0 → 6.0.1

package/src/hooks/api/create-store-api.ts

@@ -1,102 +1,124 @@
-import {SECRETS_MAX_LIST_LIMIT, type SecretWriteWarningDto} from '@shipfox/api-secrets-dto';
-import {apiRequest} from '@shipfox/client-api';
-import {useMutation, useQuery, useQueryClient} from '@tanstack/react-query';
+import {SECRETS_MAX_LIST_LIMIT} from '@shipfox/api-secrets-dto';
+import {
+  checkedApiRequest,
+  emptyResponseSchema,
+  type StandardSchema,
+  type StandardSchemaOutput,
+} from '@shipfox/client-api';
+import {
+  type FetchQueryOptions,
+  queryOptions,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query';
+import {
+  type DeleteStoreCommand,
+  type PutStoreCommand,
+  projectIdFromScope,
+  type StoreScope,
+  type StoreWriteWarning,
+  workspaceStoreScope,
+} from '#core/store.js';
 
-/**
- * Secrets and variables share an identical management surface (list / put /
- * delete under `/workspaces/:id/{resource}`); only the response envelope keys
- * and DTO types differ. This factory builds the typed transport functions,
- * query keys, and React Query hooks for one resource so `secrets.ts` and
- * `variables.ts` stay thin instantiations. The forms and sections diverge
- * (write-only vs readable) and are kept separate on purpose.
- */
-export interface CreateStoreApiConfig<TItem, TListResponse, TPutResponse> {
-  /** URL segment and query-key namespace, e.g. `'secrets'` or `'variables'`. */
-  resource: string;
-  /** Pulls the item array out of a list response. */
-  listItems: (response: TListResponse) => TItem[];
-  /** Pulls the single item out of a put response. */
-  putItem: (response: TPutResponse) => TItem;
-}
-
-export interface PutResult<TItem> {
-  item: TItem;
-  warnings: SecretWriteWarningDto[];
-}
+type StoreApiConfig<
+  TListItem,
+  TPutItem,
+  TListSchema extends StandardSchema,
+  TPutSchema extends StandardSchema,
+> = {
+  resource: 'secrets' | 'variables';
+  listResponseSchema: TListSchema;
+  putResponseSchema: TPutSchema;
+  toListItems: (response: StandardSchemaOutput<TListSchema>) => TListItem[];
+  toPutResult: (response: StandardSchemaOutput<TPutSchema>) => {
+    item: TPutItem;
+    warnings: StoreWriteWarning[];
+  };
+};
 
 export function createStoreApi<
-  TItem,
-  TListResponse,
-  TPutBody,
-  TPutResponse extends {warnings: SecretWriteWarningDto[]},
->(config: CreateStoreApiConfig<TItem, TListResponse, TPutResponse>) {
-  const {resource, listItems, putItem} = config;
-
+  TListItem,
+  TPutItem,
+  TListSchema extends StandardSchema,
+  TPutSchema extends StandardSchema,
+>(config: StoreApiConfig<TListItem, TPutItem, TListSchema, TPutSchema>) {
+  const {resource} = config;
   const queryKeys = {
     all: [resource] as const,
-    list: (workspaceId: string) => [resource, 'list', workspaceId] as const,
+    list: (workspaceId: string, scope: StoreScope = workspaceStoreScope) =>
+      [...queryKeys.all, 'list', workspaceId, scope] as const,
   };
 
-  // The store is a bounded set (per-workspace cap), so the UI fetches every key
-  // in one call rather than paginating: request the max limit and ignore the
-  // cursor. See SECRETS_MAX_LIST_LIMIT / the S1a list route.
+  type ListQueryOptions = FetchQueryOptions<
+    TListItem[],
+    Error,
+    TListItem[],
+    ReturnType<typeof queryKeys.list>
+  >;
+
+  function searchForScope(scope: StoreScope, includeLimit = false): string {
+    const search = new URLSearchParams();
+    if (includeLimit) search.set('limit', String(SECRETS_MAX_LIST_LIMIT));
+    const projectId = projectIdFromScope(scope);
+    if (projectId) search.set('project_id', projectId);
+    return search.toString();
+  }
+
   async function listAll(params: {
     workspaceId: string;
-    projectId?: string | undefined;
+    scope?: StoreScope;
     signal?: AbortSignal | undefined;
-  }): Promise<TItem[]> {
-    const search = new URLSearchParams({limit: String(SECRETS_MAX_LIST_LIMIT)});
-    if (params.projectId) search.set('project_id', params.projectId);
-    const response = await apiRequest<TListResponse>(
-      `/workspaces/${params.workspaceId}/${resource}?${search.toString()}`,
+  }): Promise<TListItem[]> {
+    const scope = params.scope ?? workspaceStoreScope;
+    const response = await checkedApiRequest(
+      config.listResponseSchema,
+      `/workspaces/${params.workspaceId}/${resource}?${searchForScope(scope, true)}`,
       {signal: params.signal},
     );
-    return listItems(response);
+    return config.toListItems(response);
   }
 
-  async function put(params: {
-    workspaceId: string;
-    key: string;
-    body: TPutBody;
-  }): Promise<PutResult<TItem>> {
-    const response = await apiRequest<TPutResponse>(
-      `/workspaces/${params.workspaceId}/${resource}/${encodeURIComponent(params.key)}`,
-      {method: 'PUT', body: params.body},
+  async function put(command: PutStoreCommand) {
+    const response = await checkedApiRequest(
+      config.putResponseSchema,
+      `/workspaces/${command.workspaceId}/${resource}/${encodeURIComponent(command.key)}`,
+      {
+        method: 'PUT',
+        body: {value: command.value, project_id: projectIdFromScope(command.scope)},
+      },
     );
-    return {item: putItem(response), warnings: response.warnings};
+    return config.toPutResult(response);
   }
 
-  async function remove(params: {
-    workspaceId: string;
-    key: string;
-    projectId?: string | undefined;
-  }): Promise<void> {
-    const search = params.projectId
-      ? `?${new URLSearchParams({project_id: params.projectId}).toString()}`
-      : '';
-    await apiRequest<void>(
-      `/workspaces/${params.workspaceId}/${resource}/${encodeURIComponent(params.key)}${search}`,
+  async function remove(command: DeleteStoreCommand): Promise<void> {
+    const search = searchForScope(command.scope);
+    await checkedApiRequest(
+      emptyResponseSchema,
+      `/workspaces/${command.workspaceId}/${resource}/${encodeURIComponent(command.key)}${search ? `?${search}` : ''}`,
       {method: 'DELETE'},
     );
   }
 
-  function useListQuery(workspaceId: string | undefined) {
-    return useQuery({
-      queryKey: workspaceId ? queryKeys.list(workspaceId) : [resource, 'list'],
-      enabled: Boolean(workspaceId),
-      queryFn: ({signal}) => listAll({workspaceId: workspaceId ?? '', signal}),
+  function listQueryOptions(
+    workspaceId: string,
+    scope: StoreScope = workspaceStoreScope,
+  ): ListQueryOptions {
+    return queryOptions({
+      queryKey: queryKeys.list(workspaceId, scope),
+      queryFn: ({signal}) => listAll({workspaceId, scope, signal}),
     });
   }
 
+  function useListQuery(workspaceId: string | undefined, scope: StoreScope = workspaceStoreScope) {
+    return useQuery({...listQueryOptions(workspaceId ?? '', scope), enabled: Boolean(workspaceId)});
+  }
+
   function usePutMutation() {
     const queryClient = useQueryClient();
     return useMutation({
       mutationFn: put,
-      // Invalidate the whole resource namespace so the per-item detail cache
-      // (full variable values) is refreshed too, not just the list.
-      onSuccess: async () => {
-        await queryClient.invalidateQueries({queryKey: queryKeys.all});
-      },
+      onSuccess: async () => await queryClient.invalidateQueries({queryKey: queryKeys.all}),
     });
   }
 
@@ -104,11 +126,18 @@ export function createStoreApi<
     const queryClient = useQueryClient();
     return useMutation({
       mutationFn: remove,
-      onSuccess: async () => {
-        await queryClient.invalidateQueries({queryKey: queryKeys.all});
-      },
+      onSuccess: async () => await queryClient.invalidateQueries({queryKey: queryKeys.all}),
     });
   }
 
-  return {queryKeys, listAll, put, remove, useListQuery, usePutMutation, useDeleteMutation};
+  return {
+    queryKeys,
+    listAll,
+    put,
+    remove,
+    listQueryOptions,
+    useListQuery,
+    usePutMutation,
+    useDeleteMutation,
+  };
 }

package/src/hooks/api/secrets.test.ts

@@ -1,11 +1,11 @@
 import {SECRETS_MAX_LIST_LIMIT} from '@shipfox/api-secrets-dto';
 import {configureApiClient} from '@shipfox/client-api';
+import {workspaceStoreScope} from '#core/store.js';
 import {
   SECRETS_TEST_WORKSPACE_ID,
   secret,
   secretsListResponse,
   variable,
-  variableListItem,
   variablesListResponse,
 } from '#test/fixtures/secrets.js';
 import {deleteSecret, listSecrets, putSecret} from './secrets.js';
@@ -32,7 +32,7 @@ describe('store transport', () => {
 
     const request = fetchImpl.mock.calls[0]?.[0] as Request;
     expect(fetchImpl).toHaveBeenCalledTimes(1);
-    expect(result).toEqual([secret()]);
+    expect(result).toMatchObject([{key: 'MY_TOKEN', scope: {kind: 'workspace'}}]);
     expect(request.method).toBe('GET');
     expect(request.url).toBe(
       `https://api.example.test/workspaces/${SECRETS_TEST_WORKSPACE_ID}/secrets?limit=${SECRETS_MAX_LIST_LIMIT}`,
@@ -64,7 +64,8 @@ describe('store transport', () => {
     const result = await putSecret({
       workspaceId: SECRETS_TEST_WORKSPACE_ID,
       key: 'MY_TOKEN',
-      body: {value: 'short'},
+      value: 'short',
+      scope: workspaceStoreScope,
     });
 
     const request = fetchImpl.mock.calls[0]?.[0] as Request;
@@ -74,14 +75,18 @@ describe('store transport', () => {
     );
     expect(requestBody).toEqual({value: 'short'});
     expect(result.warnings).toEqual([{code: 'short-secret-value', key: 'MY_TOKEN'}]);
-    expect(result.item.key).toBe('MY_TOKEN');
+    expect(result.item).toMatchObject({key: 'MY_TOKEN', scope: {kind: 'workspace'}});
   });
 
   test('deletes a secret with a 204 and no project scope by default', async () => {
     const fetchImpl = vi.fn().mockResolvedValue(new Response(null, {status: 204}));
     configureApiClient({fetchImpl});
 
-    const result = await deleteSecret({workspaceId: SECRETS_TEST_WORKSPACE_ID, key: 'MY_TOKEN'});
+    const result = await deleteSecret({
+      workspaceId: SECRETS_TEST_WORKSPACE_ID,
+      key: 'MY_TOKEN',
+      scope: workspaceStoreScope,
+    });
 
     const request = fetchImpl.mock.calls[0]?.[0] as Request;
     expect(result).toBeUndefined();
@@ -98,7 +103,7 @@ describe('store transport', () => {
     const result = await listVariables({workspaceId: SECRETS_TEST_WORKSPACE_ID});
 
     const request = fetchImpl.mock.calls[0]?.[0] as Request;
-    expect(result).toEqual([variableListItem()]);
+    expect(result).toMatchObject([{key: 'LOG_LEVEL', value: 'debug', valueState: 'preview'}]);
     expect(request.url).toBe(
       `https://api.example.test/workspaces/${SECRETS_TEST_WORKSPACE_ID}/variables?limit=${SECRETS_MAX_LIST_LIMIT}`,
     );
@@ -113,7 +118,7 @@ describe('store transport', () => {
     const result = await getVariable({workspaceId: SECRETS_TEST_WORKSPACE_ID, key: 'LOG_LEVEL'});
 
     const request = fetchImpl.mock.calls[0]?.[0] as Request;
-    expect(result.value).toBe('first line\nsecond line');
+    expect(result).toMatchObject({value: 'first line\nsecond line', valueState: 'full'});
     expect(request.method).toBe('GET');
     expect(request.url).toBe(
       `https://api.example.test/workspaces/${SECRETS_TEST_WORKSPACE_ID}/variables/LOG_LEVEL`,
@@ -132,11 +137,12 @@ describe('store transport', () => {
     const result = await putVariable({
       workspaceId: SECRETS_TEST_WORKSPACE_ID,
       key: 'MY_KEY',
-      body: {value: 'v'},
+      value: 'v',
+      scope: workspaceStoreScope,
     });
 
     expect(result.warnings).toEqual([{code: 'sensitive-variable-name', key: 'MY_KEY'}]);
-    expect(result.item.value).toBe('v');
+    expect(result.item).toMatchObject({value: 'v', valueState: 'full'});
   });
 
   test('deletes a variable within a project scope via project_id query', async () => {
@@ -146,7 +152,7 @@ describe('store transport', () => {
     await deleteVariable({
       workspaceId: SECRETS_TEST_WORKSPACE_ID,
       key: 'LOG_LEVEL',
-      projectId: '33333333-3333-4333-8333-333333333333',
+      scope: {kind: 'project', projectId: '33333333-3333-4333-8333-333333333333'},
     });
 
     const request = fetchImpl.mock.calls[0]?.[0] as Request;

package/src/hooks/api/secrets.ts

@@ -1,26 +1,23 @@
-import type {
-  ListSecretsResponseDto,
-  PutSecretBodyDto,
-  PutSecretResponseDto,
-  SecretDto,
-} from '@shipfox/api-secrets-dto';
+import {listSecretsResponseSchema, putSecretResponseSchema} from '@shipfox/api-secrets-dto';
 import {createStoreApi} from './create-store-api.js';
+import {toSecretMetadata, toStoreWriteWarnings} from './store-mapper.js';
 
-const secretsApi = createStoreApi<
-  SecretDto,
-  ListSecretsResponseDto,
-  PutSecretBodyDto,
-  PutSecretResponseDto
->({
+const secretsApi = createStoreApi({
   resource: 'secrets',
-  listItems: (response) => response.secrets,
-  putItem: (response) => response.secret,
+  listResponseSchema: listSecretsResponseSchema,
+  putResponseSchema: putSecretResponseSchema,
+  toListItems: (response) => response.secrets.map(toSecretMetadata),
+  toPutResult: (response) => ({
+    item: toSecretMetadata(response.secret),
+    warnings: toStoreWriteWarnings(response.warnings),
+  }),
 });
 
 export const secretsQueryKeys = secretsApi.queryKeys;
 export const listSecrets = secretsApi.listAll;
 export const putSecret = secretsApi.put;
 export const deleteSecret = secretsApi.remove;
+export const listSecretsQueryOptions = secretsApi.listQueryOptions;
 export const useSecretsQuery = secretsApi.useListQuery;
 export const usePutSecretMutation = secretsApi.usePutMutation;
 export const useDeleteSecretMutation = secretsApi.useDeleteMutation;

package/src/hooks/api/store-mapper.test.ts

@@ -0,0 +1,39 @@
+import {secret, variable, variableListItem} from '#test/fixtures/secrets.js';
+import {
+  toSecretMetadata,
+  toStoreWriteWarnings,
+  toVariable,
+  toVariablePreview,
+} from './store-mapper.js';
+
+describe('store transport mapping', () => {
+  test('maps secret metadata and workspace scope into a package-owned model', () => {
+    expect(toSecretMetadata(secret())).toEqual({
+      key: 'MY_TOKEN',
+      scope: {kind: 'workspace'},
+      createdAt: '2026-05-08T00:00:00.000Z',
+      updatedAt: '2026-05-08T00:00:00.000Z',
+      lastEditedBy: '22222222-2222-4222-8222-222222222222',
+    });
+  });
+
+  test('keeps truncated list values distinct from full detail values', () => {
+    expect(
+      toVariablePreview(variableListItem({value: 'preview', value_truncated: true})),
+    ).toMatchObject({
+      value: 'preview',
+      valueState: 'preview',
+      valueTruncated: true,
+    });
+    expect(toVariable(variable({value: 'complete value'}))).toMatchObject({
+      value: 'complete value',
+      valueState: 'full',
+    });
+  });
+
+  test('maps server warning DTOs to the store warning model', () => {
+    expect(toStoreWriteWarnings([{code: 'short-secret-value', key: 'MY_TOKEN'}])).toEqual([
+      {code: 'short-secret-value', key: 'MY_TOKEN'},
+    ]);
+  });
+});

package/src/hooks/api/store-mapper.ts

@@ -0,0 +1,47 @@
+import type {
+  SecretDto,
+  SecretWriteWarningDto,
+  VariableDto,
+  VariableListItemDto,
+} from '@shipfox/api-secrets-dto';
+import type {
+  SecretMetadata,
+  StoreMetadata,
+  StoreWriteWarning,
+  Variable,
+  VariablePreview,
+} from '#core/store.js';
+import {scopeFromProjectId} from '#core/store.js';
+
+function toStoreMetadata(item: SecretDto): StoreMetadata {
+  return {
+    key: item.key,
+    scope: scopeFromProjectId(item.project_id),
+    createdAt: item.created_at,
+    updatedAt: item.updated_at,
+    lastEditedBy: item.last_edited_by,
+  };
+}
+
+export function toSecretMetadata(secret: SecretDto): SecretMetadata {
+  return toStoreMetadata(secret);
+}
+
+export function toVariablePreview(variable: VariableListItemDto): VariablePreview {
+  return {
+    ...toStoreMetadata(variable),
+    value: variable.value,
+    valueState: 'preview',
+    valueTruncated: variable.value_truncated,
+  };
+}
+
+export function toVariable(variable: VariableDto): Variable {
+  return {...toStoreMetadata(variable), value: variable.value, valueState: 'full'};
+}
+
+export function toStoreWriteWarnings(
+  warnings: readonly SecretWriteWarningDto[],
+): StoreWriteWarning[] {
+  return warnings.map((warning) => ({code: warning.code, key: warning.key}));
+}

package/src/hooks/api/variables.ts

@@ -1,61 +1,77 @@
-import type {
-  GetVariableResponseDto,
-  ListVariablesResponseDto,
-  PutVariableBodyDto,
-  PutVariableResponseDto,
-  VariableDto,
-  VariableListItemDto,
+import {
+  getVariableResponseSchema,
+  listVariablesResponseSchema,
+  putVariableResponseSchema,
 } from '@shipfox/api-secrets-dto';
-import {apiRequest} from '@shipfox/client-api';
-import {useQuery} from '@tanstack/react-query';
+import {checkedApiRequest} from '@shipfox/client-api';
+import {type FetchQueryOptions, queryOptions, useQuery} from '@tanstack/react-query';
+import {
+  projectIdFromScope,
+  type StoreScope,
+  type Variable,
+  workspaceStoreScope,
+} from '#core/store.js';
 import {createStoreApi} from './create-store-api.js';
+import {toStoreWriteWarnings, toVariable, toVariablePreview} from './store-mapper.js';
 
-const variablesApi = createStoreApi<
-  VariableListItemDto,
-  ListVariablesResponseDto,
-  PutVariableBodyDto,
-  PutVariableResponseDto
->({
+const variablesApi = createStoreApi({
   resource: 'variables',
-  listItems: (response) => response.variables,
-  // The list carries only a preview; a freshly-written value is the full value.
-  putItem: (response) => ({...response.variable, value_truncated: false}),
+  listResponseSchema: listVariablesResponseSchema,
+  putResponseSchema: putVariableResponseSchema,
+  toListItems: (response) => response.variables.map(toVariablePreview),
+  toPutResult: (response) => ({
+    item: toVariable(response.variable),
+    warnings: toStoreWriteWarnings(response.warnings),
+  }),
 });
 
 export const variablesQueryKeys = variablesApi.queryKeys;
 export const listVariables = variablesApi.listAll;
 export const putVariable = variablesApi.put;
 export const deleteVariable = variablesApi.remove;
+export const listVariablesQueryOptions = variablesApi.listQueryOptions;
 export const useVariablesQuery = variablesApi.useListQuery;
 export const usePutVariableMutation = variablesApi.usePutMutation;
 export const useDeleteVariableMutation = variablesApi.useDeleteMutation;
 
-/**
- * Reads a single variable including its full value. The list only returns a
- * bounded preview, so editing a truncated variable fetches the full value here.
- */
+export const variableQueryKey = (workspaceId: string, key: string, scope: StoreScope) =>
+  [...variablesQueryKeys.all, 'detail', workspaceId, key, scope] as const;
+
+type VariableQueryOptions = FetchQueryOptions<
+  Variable,
+  Error,
+  Variable,
+  ReturnType<typeof variableQueryKey>
+>;
+
 export async function getVariable(params: {
   workspaceId: string;
   key: string;
-  projectId?: string | undefined;
+  scope?: StoreScope;
   signal?: AbortSignal | undefined;
-}): Promise<VariableDto> {
-  const search = params.projectId
-    ? `?${new URLSearchParams({project_id: params.projectId}).toString()}`
-    : '';
-  const response = await apiRequest<GetVariableResponseDto>(
+}) {
+  const scope = params.scope ?? workspaceStoreScope;
+  const projectId = projectIdFromScope(scope);
+  const search = projectId ? `?${new URLSearchParams({project_id: projectId}).toString()}` : '';
+  const response = await checkedApiRequest(
+    getVariableResponseSchema,
     `/workspaces/${params.workspaceId}/variables/${encodeURIComponent(params.key)}${search}`,
     {signal: params.signal},
   );
-  return response.variable;
+  return toVariable(response.variable);
 }
 
-export function useVariableQuery(workspaceId: string, key: string | undefined) {
-  return useQuery({
-    queryKey: key
-      ? [...variablesQueryKeys.all, 'detail', workspaceId, key]
-      : [...variablesQueryKeys.all, 'detail'],
-    enabled: Boolean(key),
-    queryFn: ({signal}) => getVariable({workspaceId, key: key ?? '', signal}),
+export function variableQueryOptions(
+  workspaceId: string,
+  key: string,
+  scope: StoreScope = workspaceStoreScope,
+): VariableQueryOptions {
+  return queryOptions({
+    queryKey: variableQueryKey(workspaceId, key, scope),
+    queryFn: ({signal}) => getVariable({workspaceId, key, scope, signal}),
   });
 }
+
+export function useVariableQuery(workspaceId: string, key: string | undefined) {
+  return useQuery({...variableQueryOptions(workspaceId, key ?? ''), enabled: Boolean(key)});
+}