@unisource/sdk 0.1.2 → 0.2.0

package/src/fileRecords.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { nonEmptyString, positiveInt, uploadDestinationSchema } from './primitives';
+
+// ─── User-facing file record ──────────────────────────────────────────────────
+
+/**
+ * A confirmed file record owned by a user.
+ * Internal fields (storage_key, bucket) are intentionally excluded from the public API.
+ */
+export const fileRecordSchema = z.object({
+  id: nonEmptyString,
+  service_id: nonEmptyString,
+  user_id: nonEmptyString,
+  folder_id: nonEmptyString.nullable(),
+  upload_id: nonEmptyString.nullable(),
+  filename: nonEmptyString,
+  size: positiveInt,
+  mime_type: nonEmptyString,
+  storage_destination: uploadDestinationSchema,
+  is_trashed: z.boolean(),
+  trashed_at: positiveInt.nullable(),
+  created_at: positiveInt,
+  updated_at: positiveInt,
+});
+export type FileRecord = z.infer<typeof fileRecordSchema>;
+
+// ─── List ─────────────────────────────────────────────────────────────────────
+
+export const FILES_DEFAULT_LIMIT = 25;
+export const FILES_MAX_LIMIT = 100;
+
+export const fileRecordsListQuerySchema = z.object({
+  folder_id: nonEmptyString.nullable().optional(),
+  is_trashed: z.boolean().optional(),
+  cursor: nonEmptyString.optional(),
+  limit: z.number().int().min(1).max(FILES_MAX_LIMIT).optional(),
+});
+export type FileRecordsListQuery = z.infer<typeof fileRecordsListQuerySchema>;
+
+export const fileRecordsListResponseSchema = z.object({
+  items: z.array(fileRecordSchema),
+  next_cursor: z.string().nullable(),
+  limit: positiveInt,
+});
+export type FileRecordsListResponse = z.infer<typeof fileRecordsListResponseSchema>;
+
+// ─── Single file detail ───────────────────────────────────────────────────────
+
+export const fileRecordDetailResponseSchema = z.object({
+  file: fileRecordSchema,
+});
+export type FileRecordDetailResponse = z.infer<typeof fileRecordDetailResponseSchema>;
+
+// ─── Move ────────────────────────────────────────────────────────────────────
+
+export const fileMoveRequestSchema = z.object({
+  /** null = move to root, undefined = keep unchanged */
+  folder_id: nonEmptyString.nullable().optional(),
+});
+export type FileMoveRequest = z.infer<typeof fileMoveRequestSchema>;
+
+// ─── Download URL ─────────────────────────────────────────────────────────────
+
+export const fileDownloadUrlResponseSchema = z.object({
+  upload_id: nonEmptyString,
+  destination: uploadDestinationSchema,
+  download_url: z.string().url(),
+  expires_at: positiveInt,
+});
+export type FileDownloadUrlResponse = z.infer<typeof fileDownloadUrlResponseSchema>;
+
+// ─── Delete ───────────────────────────────────────────────────────────────────
+
+export const fileDeleteResponseSchema = z.object({
+  success: z.literal(true),
+  id: nonEmptyString,
+  permanent: z.boolean(),
+});
+export type FileDeleteResponse = z.infer<typeof fileDeleteResponseSchema>;
+
+// ─── Restore ──────────────────────────────────────────────────────────────────
+
+export const fileRestoreResponseSchema = z.object({
+  success: z.literal(true),
+  id: nonEmptyString,
+});
+export type FileRestoreResponse = z.infer<typeof fileRestoreResponseSchema>;

package/src/folders.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { nonEmptyString, positiveInt } from './primitives';
+
+// ─── Folder record ────────────────────────────────────────────────────────────
+
+export const folderSchema = z.object({
+  id: nonEmptyString,
+  service_id: nonEmptyString,
+  user_id: nonEmptyString,
+  parent_id: nonEmptyString.nullable(),
+  name: nonEmptyString,
+  color_tag: z.string().nullable(),
+  is_trashed: z.boolean(),
+  trashed_at: positiveInt.nullable(),
+  created_at: positiveInt,
+  updated_at: positiveInt,
+});
+export type Folder = z.infer<typeof folderSchema>;
+
+// ─── List ─────────────────────────────────────────────────────────────────────
+
+export const folderListQuerySchema = z.object({
+  parent_id: nonEmptyString.nullable().optional(),
+  is_trashed: z.boolean().optional(),
+  cursor: nonEmptyString.optional(),
+  limit: z.number().int().min(1).max(100).optional(),
+});
+export type FolderListQuery = z.infer<typeof folderListQuerySchema>;
+
+export const folderListResponseSchema = z.object({
+  items: z.array(folderSchema),
+  next_cursor: z.string().nullable(),
+  limit: positiveInt,
+});
+export type FolderListResponse = z.infer<typeof folderListResponseSchema>;
+
+// ─── Create ───────────────────────────────────────────────────────────────────
+
+export const folderCreateRequestSchema = z.object({
+  name: nonEmptyString,
+  parent_id: nonEmptyString.optional(),
+  color_tag: z.string().optional(),
+});
+export type FolderCreateRequest = z.infer<typeof folderCreateRequestSchema>;
+
+export const folderCreateResponseSchema = z.object({
+  folder: folderSchema,
+});
+export type FolderCreateResponse = z.infer<typeof folderCreateResponseSchema>;
+
+// ─── Update ───────────────────────────────────────────────────────────────────
+
+export const folderUpdateRequestSchema = z
+  .object({
+    name: nonEmptyString.optional(),
+    color_tag: z.string().nullable().optional(),
+  })
+  .refine((v) => v.name !== undefined || v.color_tag !== undefined, {
+    message: 'At least one of name or color_tag must be provided',
+  });
+export type FolderUpdateRequest = z.infer<typeof folderUpdateRequestSchema>;
+
+export const folderUpdateResponseSchema = z.object({
+  folder: folderSchema,
+});
+export type FolderUpdateResponse = z.infer<typeof folderUpdateResponseSchema>;
+
+// ─── Delete ───────────────────────────────────────────────────────────────────
+
+export const folderDeleteResponseSchema = z.object({
+  success: z.literal(true),
+  id: nonEmptyString,
+  permanent: z.boolean(),
+  folders_deleted: z.number().int().nonnegative().optional(),
+});
+export type FolderDeleteResponse = z.infer<typeof folderDeleteResponseSchema>;
+
+// ─── Restore ──────────────────────────────────────────────────────────────────
+
+export const folderRestoreResponseSchema = z.object({
+  success: z.literal(true),
+  id: nonEmptyString,
+});
+export type FolderRestoreResponse = z.infer<typeof folderRestoreResponseSchema>;

package/src/index.ts

@@ -1,125 +1,106 @@
-import { z } from 'zod';
-
-export const FILES_DEFAULT_LIMIT = 25;
-export const FILES_MAX_LIMIT = 100;
-
-const nonEmptyStringSchema = z.string().trim().min(1);
-const positiveIntegerSchema = z.number().int().positive();
-
-export const uploadDestinationSchema = z.enum(['r2', 'appwrite']);
-export type UploadDestination = z.infer<typeof uploadDestinationSchema>;
-
-export const uploadStatusSchema = z.enum(['pending', 'completed', 'failed']);
-export type UploadStatus = z.infer<typeof uploadStatusSchema>;
-
-export const apiErrorSchema = z.object({
-  error: nonEmptyStringSchema,
-  message: nonEmptyStringSchema,
-});
-export type ApiError = z.infer<typeof apiErrorSchema>;
-
-export const uploadR2InitRequestSchema = z.object({
-  filename: nonEmptyStringSchema,
-  size: positiveIntegerSchema,
-  mime_type: nonEmptyStringSchema,
-  bucket: nonEmptyStringSchema.optional(),
-});
-export type UploadR2InitRequest = z.infer<typeof uploadR2InitRequestSchema>;
-
-export const uploadR2InitResponseSchema = z.object({
-  upload_id: nonEmptyStringSchema,
-  destination: z.literal('r2'),
-  presigned_url: z.string().url(),
-  storage_key: nonEmptyStringSchema,
-  bucket: nonEmptyStringSchema,
-  expires_at: positiveIntegerSchema,
-});
-export type UploadR2InitResponse = z.infer<typeof uploadR2InitResponseSchema>;
-
-export const uploadAppwriteInitRequestSchema = z.object({
-  filename: nonEmptyStringSchema,
-  size: positiveIntegerSchema,
-  mime_type: nonEmptyStringSchema,
-});
-export type UploadAppwriteInitRequest = z.infer<typeof uploadAppwriteInitRequestSchema>;
-
-export const uploadAppwriteInitResponseSchema = z.object({
-  upload_id: nonEmptyStringSchema,
-  destination: z.literal('appwrite'),
-  appwrite_endpoint: z.string().url(),
-  appwrite_project_id: nonEmptyStringSchema,
-  appwrite_bucket_id: nonEmptyStringSchema,
-  file_id: nonEmptyStringSchema,
-  expires_at: positiveIntegerSchema,
-});
-export type UploadAppwriteInitResponse = z.infer<typeof uploadAppwriteInitResponseSchema>;
-
-export const uploadLifecycleRequestSchema = z.object({
-  upload_id: nonEmptyStringSchema,
-});
-export type UploadLifecycleRequest = z.infer<typeof uploadLifecycleRequestSchema>;
-
-export const uploadCompleteResponseSchema = z.object({
-  success: z.literal(true),
-  upload_id: nonEmptyStringSchema,
-  status: z.literal('completed'),
-});
-export type UploadCompleteResponse = z.infer<typeof uploadCompleteResponseSchema>;
-
-export const uploadFailResponseSchema = z.object({
-  success: z.literal(true),
-  upload_id: nonEmptyStringSchema,
-  status: z.literal('failed'),
-});
-export type UploadFailResponse = z.infer<typeof uploadFailResponseSchema>;
-
-export const fileRecordSchema = z.object({
-  id: nonEmptyStringSchema,
-  filename: nonEmptyStringSchema,
-  size: positiveIntegerSchema,
-  mime_type: nonEmptyStringSchema,
-  destination: uploadDestinationSchema,
-  storage_key: nonEmptyStringSchema,
-  bucket: nonEmptyStringSchema,
-  status: uploadStatusSchema,
-  expires_at: positiveIntegerSchema,
-  created_at: positiveIntegerSchema,
-  updated_at: positiveIntegerSchema,
-});
-export type FileRecord = z.infer<typeof fileRecordSchema>;
-
-export const filesListQuerySchema = z.object({
-  limit: z.number().int().min(1).max(FILES_MAX_LIMIT).optional(),
-  cursor: nonEmptyStringSchema.optional(),
-  destination: uploadDestinationSchema.optional(),
-  status: uploadStatusSchema.optional(),
-});
-export type FilesListQuery = z.infer<typeof filesListQuerySchema>;
-
-export const filesListResponseSchema = z.object({
-  items: z.array(fileRecordSchema),
-  next_cursor: z.string().nullable(),
-  limit: z.number().int().min(1).max(FILES_MAX_LIMIT),
-});
-export type FilesListResponse = z.infer<typeof filesListResponseSchema>;
-
-export const fileDetailsResponseSchema = z.object({
-  file: fileRecordSchema,
-});
-export type FileDetailsResponse = z.infer<typeof fileDetailsResponseSchema>;
-
-export const fileDownloadUrlResponseSchema = z.object({
-  upload_id: nonEmptyStringSchema,
-  destination: uploadDestinationSchema,
-  download_url: z.string().url(),
-  expires_at: positiveIntegerSchema,
-});
-export type FileDownloadUrlResponse = z.infer<typeof fileDownloadUrlResponseSchema>;
-
-export const fileDeleteResponseSchema = z.object({
-  success: z.literal(true),
-  upload_id: nonEmptyStringSchema,
-  destination: uploadDestinationSchema,
-  storage_not_found: z.boolean(),
-});
-export type FileDeleteResponse = z.infer<typeof fileDeleteResponseSchema>;
+// ─── Primitives ───────────────────────────────────────────────────────────────
+export {
+  nonEmptyString,
+  positiveInt,
+  unixTimestamp,
+  uploadDestinationSchema,
+  uploadStatusSchema,
+  apiErrorSchema,
+} from './primitives';
+export type { UploadDestination, UploadStatus, ApiError } from './primitives';
+
+// ─── Upload ───────────────────────────────────────────────────────────────────
+export {
+  FILES_DEFAULT_LIMIT,
+  FILES_MAX_LIMIT,
+  uploadR2InitRequestSchema,
+  uploadR2InitResponseSchema,
+  uploadAppwriteInitRequestSchema,
+  uploadAppwriteInitResponseSchema,
+  uploadLifecycleRequestSchema,
+  uploadCompleteResponseSchema,
+  uploadFailResponseSchema,
+  uploadRecordSchema,
+  uploadsListResponseSchema,
+} from './uploads';
+export type {
+  UploadR2InitRequest,
+  UploadR2InitResponse,
+  UploadAppwriteInitRequest,
+  UploadAppwriteInitResponse,
+  UploadLifecycleRequest,
+  UploadCompleteResponse,
+  UploadFailResponse,
+  UploadRecord,
+  UploadsListResponse,
+} from './uploads';
+
+// ─── File Records ─────────────────────────────────────────────────────────────
+export {
+  fileRecordSchema,
+  fileRecordsListQuerySchema,
+  fileRecordsListResponseSchema,
+  fileRecordDetailResponseSchema,
+  fileMoveRequestSchema,
+  fileDownloadUrlResponseSchema,
+  fileDeleteResponseSchema,
+  fileRestoreResponseSchema,
+} from './fileRecords';
+export type {
+  FileRecord,
+  FileRecordsListQuery,
+  FileRecordsListResponse,
+  FileRecordDetailResponse,
+  FileMoveRequest,
+  FileDownloadUrlResponse,
+  FileDeleteResponse,
+  FileRestoreResponse,
+} from './fileRecords';
+
+// ─── Folders ─────────────────────────────────────────────────────────────────
+export {
+  folderSchema,
+  folderListQuerySchema,
+  folderListResponseSchema,
+  folderCreateRequestSchema,
+  folderCreateResponseSchema,
+  folderUpdateRequestSchema,
+  folderUpdateResponseSchema,
+  folderDeleteResponseSchema,
+  folderRestoreResponseSchema,
+} from './folders';
+export type {
+  Folder,
+  FolderListQuery,
+  FolderListResponse,
+  FolderCreateRequest,
+  FolderCreateResponse,
+  FolderUpdateRequest,
+  FolderUpdateResponse,
+  FolderDeleteResponse,
+  FolderRestoreResponse,
+} from './folders';
+
+// ─── Services & Audit ─────────────────────────────────────────────────────────
+export {
+  serviceSchema,
+  serviceDetailResponseSchema,
+  serviceUsageResponseSchema,
+  auditEventActionSchema,
+  auditEventSchema,
+  auditLogListQuerySchema,
+  auditLogListResponseSchema,
+} from './services';
+export type {
+  Service,
+  ServiceDetailResponse,
+  ServiceUsageResponse,
+  AuditEventAction,
+  AuditEvent,
+  AuditLogListQuery,
+  AuditLogListResponse,
+} from './services';
+
+// ─── HTTP Client ─────────────────────────────────────────────────────────────
+export { UnisourceClient, UnisourceError, UnisourceNetworkError } from './client';
+export type { UnisourceClientConfig } from './client';

package/src/primitives.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+// ─── Primitives ─────────────────────────────────────────────────────────────
+
+export const nonEmptyString = z.string().trim().min(1);
+export const positiveInt = z.number().int().positive();
+export const unixTimestamp = z.number().int().nonnegative();
+
+// ─── Upload Destination ──────────────────────────────────────────────────────
+
+export const uploadDestinationSchema = z.enum(['r2', 'appwrite']);
+export type UploadDestination = z.infer<typeof uploadDestinationSchema>;
+
+// ─── Upload Status ────────────────────────────────────────────────────────────
+
+export const uploadStatusSchema = z.enum(['pending', 'completed', 'failed']);
+export type UploadStatus = z.infer<typeof uploadStatusSchema>;
+
+// ─── API Error ────────────────────────────────────────────────────────────────
+
+export const apiErrorSchema = z.object({
+  error: nonEmptyString,
+  message: nonEmptyString,
+});
+export type ApiError = z.infer<typeof apiErrorSchema>;

package/src/services.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { nonEmptyString, positiveInt, unixTimestamp } from './primitives';
+
+// ─── Service record ───────────────────────────────────────────────────────────
+
+/** Public service info returned to admins. Never exposes secrets. */
+export const serviceSchema = z.object({
+  id: nonEmptyString,
+  name: nonEmptyString,
+  max_storage_bytes: positiveInt,
+  current_used_bytes: z.number().int().nonnegative(),
+  max_file_size_bytes: positiveInt,
+  created_at: unixTimestamp,
+});
+export type Service = z.infer<typeof serviceSchema>;
+
+export const serviceDetailResponseSchema = z.object({
+  service: serviceSchema,
+});
+export type ServiceDetailResponse = z.infer<typeof serviceDetailResponseSchema>;
+
+// ─── Service usage summary ────────────────────────────────────────────────────
+
+export const serviceUsageResponseSchema = z.object({
+  service_id: nonEmptyString,
+  max_storage_bytes: positiveInt,
+  current_used_bytes: z.number().int().nonnegative(),
+  used_percent: z.number().min(0).max(100),
+});
+export type ServiceUsageResponse = z.infer<typeof serviceUsageResponseSchema>;
+
+// ─── Audit log event ──────────────────────────────────────────────────────────
+
+export const auditEventActionSchema = z.enum([
+  'upload_completed',
+  'file_deleted',
+  'folder_deleted',
+  'quota_exceeded',
+]);
+export type AuditEventAction = z.infer<typeof auditEventActionSchema>;
+
+export const auditEventSchema = z.object({
+  id: nonEmptyString,
+  service_id: nonEmptyString,
+  user_id: nonEmptyString,
+  action: auditEventActionSchema,
+  resource_type: z.enum(['file', 'folder', 'service']),
+  resource_id: nonEmptyString,
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+  ip_address: z.string().nullable(),
+  created_at: unixTimestamp,
+});
+export type AuditEvent = z.infer<typeof auditEventSchema>;
+
+export const auditLogListQuerySchema = z.object({
+  user_id: nonEmptyString.optional(),
+  action: auditEventActionSchema.optional(),
+  resource_type: z.enum(['file', 'folder', 'service']).optional(),
+  cursor: nonEmptyString.optional(),
+  limit: z.number().int().min(1).max(200).optional(),
+});
+export type AuditLogListQuery = z.infer<typeof auditLogListQuerySchema>;
+
+export const auditLogListResponseSchema = z.object({
+  items: z.array(auditEventSchema),
+  next_cursor: z.string().nullable(),
+  limit: positiveInt,
+});
+export type AuditLogListResponse = z.infer<typeof auditLogListResponseSchema>;

package/src/uploadDestination.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+
+export const uploadDestinationSchema = z.enum(['r2', 'appwrite']);
+export type UploadDestination = z.infer<typeof uploadDestinationSchema>;

package/src/uploads.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { nonEmptyString, positiveInt, uploadDestinationSchema } from './primitives';
+
+// ─── Init: R2 ────────────────────────────────────────────────────────────────
+
+export const uploadR2InitRequestSchema = z.object({
+  filename: nonEmptyString,
+  size: positiveInt,
+  mime_type: nonEmptyString,
+});
+export type UploadR2InitRequest = z.infer<typeof uploadR2InitRequestSchema>;
+
+export const uploadR2InitResponseSchema = z.object({
+  upload_id: nonEmptyString,
+  destination: z.literal('r2'),
+  presigned_url: z.string().url(),
+  storage_key: nonEmptyString,
+  bucket: nonEmptyString,
+  expires_at: positiveInt,
+});
+export type UploadR2InitResponse = z.infer<typeof uploadR2InitResponseSchema>;
+
+// ─── Init: Appwrite ───────────────────────────────────────────────────────────
+
+export const uploadAppwriteInitRequestSchema = z.object({
+  filename: nonEmptyString,
+  size: positiveInt,
+  mime_type: nonEmptyString,
+});
+export type UploadAppwriteInitRequest = z.infer<typeof uploadAppwriteInitRequestSchema>;
+
+export const uploadAppwriteInitResponseSchema = z.object({
+  upload_id: nonEmptyString,
+  destination: z.literal('appwrite'),
+  appwrite_endpoint: z.string().url(),
+  appwrite_project_id: nonEmptyString,
+  appwrite_bucket_id: nonEmptyString,
+  file_id: nonEmptyString,
+  expires_at: positiveInt,
+});
+export type UploadAppwriteInitResponse = z.infer<typeof uploadAppwriteInitResponseSchema>;
+
+// ─── Lifecycle ────────────────────────────────────────────────────────────────
+
+export const uploadLifecycleRequestSchema = z.object({
+  upload_id: nonEmptyString,
+});
+export type UploadLifecycleRequest = z.infer<typeof uploadLifecycleRequestSchema>;
+
+export const uploadCompleteResponseSchema = z.object({
+  success: z.literal(true),
+  upload_id: nonEmptyString,
+  status: z.literal('completed'),
+});
+export type UploadCompleteResponse = z.infer<typeof uploadCompleteResponseSchema>;
+
+export const uploadFailResponseSchema = z.object({
+  success: z.literal(true),
+  upload_id: nonEmptyString,
+  status: z.literal('failed'),
+});
+export type UploadFailResponse = z.infer<typeof uploadFailResponseSchema>;
+
+// ─── Admin: list uploads ──────────────────────────────────────────────────────
+
+export const FILES_DEFAULT_LIMIT = 25;
+export const FILES_MAX_LIMIT = 100;
+
+/** Raw upload record — returned by admin `/files` endpoints. */
+export const uploadRecordSchema = z.object({
+  id: nonEmptyString,
+  service_id: nonEmptyString,
+  user_id: nonEmptyString.nullable(),
+  filename: nonEmptyString,
+  size: positiveInt,
+  mime_type: nonEmptyString,
+  destination: uploadDestinationSchema,
+  status: z.enum(['pending', 'completed', 'failed']),
+  expires_at: positiveInt,
+  created_at: positiveInt,
+  updated_at: positiveInt,
+});
+export type UploadRecord = z.infer<typeof uploadRecordSchema>;
+
+export const uploadsListResponseSchema = z.object({
+  items: z.array(uploadRecordSchema),
+  next_cursor: z.string().nullable(),
+  limit: positiveInt,
+});
+export type UploadsListResponse = z.infer<typeof uploadsListResponseSchema>;