@shipfox/client-secrets 0.2.0

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

@@ -0,0 +1,114 @@
+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';
+
+/**
+ * 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[];
+}
+
+export function createStoreApi<
+  TItem,
+  TListResponse,
+  TPutBody,
+  TPutResponse extends {warnings: SecretWriteWarningDto[]},
+>(config: CreateStoreApiConfig<TItem, TListResponse, TPutResponse>) {
+  const {resource, listItems, putItem} = config;
+
+  const queryKeys = {
+    all: [resource] as const,
+    list: (workspaceId: string) => [resource, 'list', workspaceId] 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.
+  async function listAll(params: {
+    workspaceId: string;
+    projectId?: string | undefined;
+    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()}`,
+      {signal: params.signal},
+    );
+    return listItems(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},
+    );
+    return {item: putItem(response), warnings: response.warnings};
+  }
+
+  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}`,
+      {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 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});
+      },
+    });
+  }
+
+  function useDeleteMutation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+      mutationFn: remove,
+      onSuccess: async () => {
+        await queryClient.invalidateQueries({queryKey: queryKeys.all});
+      },
+    });
+  }
+
+  return {queryKeys, listAll, put, remove, useListQuery, usePutMutation, useDeleteMutation};
+}

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

@@ -0,0 +1,157 @@
+import {SECRETS_MAX_LIST_LIMIT} from '@shipfox/api-secrets-dto';
+import {configureApiClient} from '@shipfox/client-api';
+import {
+  SECRETS_TEST_WORKSPACE_ID,
+  secret,
+  secretsListResponse,
+  variable,
+  variableListItem,
+  variablesListResponse,
+} from '#test/fixtures/secrets.js';
+import {deleteSecret, listSecrets, putSecret} from './secrets.js';
+import {deleteVariable, getVariable, listVariables, putVariable} from './variables.js';
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    headers: {'content-type': 'application/json'},
+    status: 200,
+    ...init,
+  });
+}
+
+describe('store transport', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('lists the whole secret set in a single call at the max limit', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(secretsListResponse()));
+    configureApiClient({fetchImpl});
+
+    const result = await listSecrets({workspaceId: SECRETS_TEST_WORKSPACE_ID});
+
+    const request = fetchImpl.mock.calls[0]?.[0] as Request;
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(result).toEqual([secret()]);
+    expect(request.method).toBe('GET');
+    expect(request.url).toBe(
+      `https://api.example.test/workspaces/${SECRETS_TEST_WORKSPACE_ID}/secrets?limit=${SECRETS_MAX_LIST_LIMIT}`,
+    );
+  });
+
+  test('returns an empty array when the store is empty', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(jsonResponse(secretsListResponse({secrets: [], next_cursor: null})));
+    configureApiClient({fetchImpl});
+
+    const result = await listSecrets({workspaceId: SECRETS_TEST_WORKSPACE_ID});
+
+    expect(result).toEqual([]);
+  });
+
+  test('puts a secret, encodes the key, and passes warnings through', async () => {
+    let requestBody: unknown;
+    const fetchImpl = vi.fn(async (input: RequestInfo | URL) => {
+      requestBody = await (input as Request).clone().json();
+      return jsonResponse({
+        secret: secret({key: 'MY_TOKEN'}),
+        warnings: [{code: 'short-secret-value', key: 'MY_TOKEN'}],
+      });
+    });
+    configureApiClient({fetchImpl});
+
+    const result = await putSecret({
+      workspaceId: SECRETS_TEST_WORKSPACE_ID,
+      key: 'MY_TOKEN',
+      body: {value: 'short'},
+    });
+
+    const request = fetchImpl.mock.calls[0]?.[0] as Request;
+    expect(request.method).toBe('PUT');
+    expect(request.url).toBe(
+      `https://api.example.test/workspaces/${SECRETS_TEST_WORKSPACE_ID}/secrets/MY_TOKEN`,
+    );
+    expect(requestBody).toEqual({value: 'short'});
+    expect(result.warnings).toEqual([{code: 'short-secret-value', key: 'MY_TOKEN'}]);
+    expect(result.item.key).toBe('MY_TOKEN');
+  });
+
+  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 request = fetchImpl.mock.calls[0]?.[0] as Request;
+    expect(result).toBeUndefined();
+    expect(request.method).toBe('DELETE');
+    expect(request.url).toBe(
+      `https://api.example.test/workspaces/${SECRETS_TEST_WORKSPACE_ID}/secrets/MY_TOKEN`,
+    );
+  });
+
+  test('lists variables (values included) via the same factory', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(jsonResponse(variablesListResponse()));
+    configureApiClient({fetchImpl});
+
+    const result = await listVariables({workspaceId: SECRETS_TEST_WORKSPACE_ID});
+
+    const request = fetchImpl.mock.calls[0]?.[0] as Request;
+    expect(result).toEqual([variableListItem()]);
+    expect(request.url).toBe(
+      `https://api.example.test/workspaces/${SECRETS_TEST_WORKSPACE_ID}/variables?limit=${SECRETS_MAX_LIST_LIMIT}`,
+    );
+  });
+
+  test('reads a single variable with its full value for editing', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(jsonResponse({variable: variable({value: 'first line\nsecond line'})}));
+    configureApiClient({fetchImpl});
+
+    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(request.method).toBe('GET');
+    expect(request.url).toBe(
+      `https://api.example.test/workspaces/${SECRETS_TEST_WORKSPACE_ID}/variables/LOG_LEVEL`,
+    );
+  });
+
+  test('puts a variable and returns the sensitive-name warning', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(
+      jsonResponse({
+        variable: variable({key: 'MY_KEY', value: 'v'}),
+        warnings: [{code: 'sensitive-variable-name', key: 'MY_KEY'}],
+      }),
+    );
+    configureApiClient({fetchImpl});
+
+    const result = await putVariable({
+      workspaceId: SECRETS_TEST_WORKSPACE_ID,
+      key: 'MY_KEY',
+      body: {value: 'v'},
+    });
+
+    expect(result.warnings).toEqual([{code: 'sensitive-variable-name', key: 'MY_KEY'}]);
+    expect(result.item.value).toBe('v');
+  });
+
+  test('deletes a variable within a project scope via project_id query', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(new Response(null, {status: 204}));
+    configureApiClient({fetchImpl});
+
+    await deleteVariable({
+      workspaceId: SECRETS_TEST_WORKSPACE_ID,
+      key: 'LOG_LEVEL',
+      projectId: '33333333-3333-4333-8333-333333333333',
+    });
+
+    const request = fetchImpl.mock.calls[0]?.[0] as Request;
+    expect(request.url).toBe(
+      `https://api.example.test/workspaces/${SECRETS_TEST_WORKSPACE_ID}/variables/LOG_LEVEL?project_id=33333333-3333-4333-8333-333333333333`,
+    );
+  });
+});

package/src/hooks/api/secrets.ts

@@ -0,0 +1,26 @@
+import type {
+  ListSecretsResponseDto,
+  PutSecretBodyDto,
+  PutSecretResponseDto,
+  SecretDto,
+} from '@shipfox/api-secrets-dto';
+import {createStoreApi} from './create-store-api.js';
+
+const secretsApi = createStoreApi<
+  SecretDto,
+  ListSecretsResponseDto,
+  PutSecretBodyDto,
+  PutSecretResponseDto
+>({
+  resource: 'secrets',
+  listItems: (response) => response.secrets,
+  putItem: (response) => response.secret,
+});
+
+export const secretsQueryKeys = secretsApi.queryKeys;
+export const listSecrets = secretsApi.listAll;
+export const putSecret = secretsApi.put;
+export const deleteSecret = secretsApi.remove;
+export const useSecretsQuery = secretsApi.useListQuery;
+export const usePutSecretMutation = secretsApi.usePutMutation;
+export const useDeleteSecretMutation = secretsApi.useDeleteMutation;

package/src/hooks/api/variables.ts

@@ -0,0 +1,61 @@
+import type {
+  GetVariableResponseDto,
+  ListVariablesResponseDto,
+  PutVariableBodyDto,
+  PutVariableResponseDto,
+  VariableDto,
+  VariableListItemDto,
+} from '@shipfox/api-secrets-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {useQuery} from '@tanstack/react-query';
+import {createStoreApi} from './create-store-api.js';
+
+const variablesApi = createStoreApi<
+  VariableListItemDto,
+  ListVariablesResponseDto,
+  PutVariableBodyDto,
+  PutVariableResponseDto
+>({
+  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}),
+});
+
+export const variablesQueryKeys = variablesApi.queryKeys;
+export const listVariables = variablesApi.listAll;
+export const putVariable = variablesApi.put;
+export const deleteVariable = variablesApi.remove;
+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 async function getVariable(params: {
+  workspaceId: string;
+  key: string;
+  projectId?: string | undefined;
+  signal?: AbortSignal | undefined;
+}): Promise<VariableDto> {
+  const search = params.projectId
+    ? `?${new URLSearchParams({project_id: params.projectId}).toString()}`
+    : '';
+  const response = await apiRequest<GetVariableResponseDto>(
+    `/workspaces/${params.workspaceId}/variables/${encodeURIComponent(params.key)}${search}`,
+    {signal: params.signal},
+  );
+  return 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}),
+  });
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export {type SecretsFormErrorMapping, secretsErrorToFormError} from './components/form-errors.js';
+export {WorkspaceSecretsSection} from './components/workspace-secrets-section.js';
+export {WorkspaceVariablesSection} from './components/workspace-variables-section.js';
+export * from './hooks/api/secrets.js';
+export * from './hooks/api/variables.js';

package/test/fixtures/secrets.ts

@@ -0,0 +1,59 @@
+import type {
+  ListSecretsResponseDto,
+  ListVariablesResponseDto,
+  SecretDto,
+  VariableDto,
+  VariableListItemDto,
+} from '@shipfox/api-secrets-dto';
+
+export const SECRETS_TEST_WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+
+export function secret(overrides: Partial<SecretDto> = {}): SecretDto {
+  return {
+    key: 'MY_TOKEN',
+    project_id: null,
+    created_at: '2026-05-08T00:00:00.000Z',
+    updated_at: '2026-05-08T00:00:00.000Z',
+    last_edited_by: '22222222-2222-4222-8222-222222222222',
+    ...overrides,
+  };
+}
+
+export function variable(overrides: Partial<VariableDto> = {}): VariableDto {
+  return {
+    ...secret(),
+    key: 'LOG_LEVEL',
+    value: 'debug',
+    ...overrides,
+  };
+}
+
+export function variableListItem(
+  overrides: Partial<VariableListItemDto> = {},
+): VariableListItemDto {
+  return {
+    ...variable(),
+    value_truncated: false,
+    ...overrides,
+  };
+}
+
+export function secretsListResponse(
+  overrides: Partial<ListSecretsResponseDto> = {},
+): ListSecretsResponseDto {
+  return {
+    secrets: [secret()],
+    next_cursor: null,
+    ...overrides,
+  };
+}
+
+export function variablesListResponse(
+  overrides: Partial<ListVariablesResponseDto> = {},
+): ListVariablesResponseDto {
+  return {
+    variables: [variableListItem()],
+    next_cursor: null,
+    ...overrides,
+  };
+}

package/test/setup.ts

@@ -0,0 +1,3 @@
+import {installClientDomTestEnv} from '@shipfox/client-test-setup';
+
+installClientDomTestEnv();

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/react",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts"]
+}