@picobase_app/client 0.2.0 → 0.5.1

package/README.md

@@ -8,7 +8,7 @@ TypeScript SDK for PicoBase — add auth, database, realtime, and file storage t
 npm install @picobase_app/client
 ```
 
-> ⚠️ **Important:** Install `@picobase_app/client`, **NOT** `pocketbase` directly. PicoBase wraps PocketBase with managed hosting features. If you accidentally installed `pocketbase`, remove it from your dependencies.
+> ⚠️ **Important:** Always install `@picobase_app/client`. If you accidentally installed `pocketbase`, remove it — that's an internal dependency, not the user-facing SDK.
 
 ## Quickstart
 
@@ -178,11 +178,11 @@ const results = await pb.rpc('search_products', {
 })
 ```
 
-RPC calls are mapped to custom PocketBase endpoints at `/api/rpc/{functionName}`. You'll need to implement these routes in your PocketBase instance. See the [PocketBase routing docs](https://pocketbase.io/docs/js-routing/) for details.
+RPC calls are mapped to custom endpoints at `/api/rpc/{functionName}`. You can implement these routes in your PicoBase instance.
 
 ## File Storage
 
-PocketBase stores files as fields on records. Use the storage module to get URLs.
+PicoBase stores files as fields on records. Use the storage module to get URLs.
 
 ```typescript
 const user = await pb.collection('users').getOne('USER_ID')
@@ -198,6 +198,39 @@ const token = await pb.storage.getFileToken()
 const protectedUrl = pb.storage.getFileUrl(user, 'document.pdf', { token })
 ```
 
+## Admin API (Collection Management)
+
+The SDK provides an admin module that allows you to programmatically manage your PicoBase collections. **This requires an admin API key** to be used during client initialization.
+
+```typescript
+// Initializing with an admin API key
+const adminPb = createClient('https://myapp.picobase.com', 'pbk_admin_xxxxxxxx')
+
+// Create a new collection
+const usersCollection = await adminPb.admin.createCollection({
+  name: "custom_users",
+  type: "base",
+  schema: [
+    { name: "full_name", type: "text", required: true },
+    { name: "age", type: "number" }
+  ]
+})
+
+// List all collections
+const collections = await adminPb.admin.listCollections()
+
+// Get a single collection
+const collection = await adminPb.admin.getCollection('custom_users')
+
+// Update an existing collection
+const updated = await adminPb.admin.updateCollection('custom_users', {
+  name: "users_updated"
+})
+
+// Delete a collection
+const success = await adminPb.admin.deleteCollection('users_updated')
+```
+
 ## Advanced
 
 ### Custom auth collection
@@ -208,12 +241,12 @@ pb.auth.setCollection('members')
 await pb.auth.signIn({ email: 'member@example.com', password: 'pass' })
 ```
 
-### Raw PocketBase access
+### Raw access (advanced)
 
-The underlying PocketBase SDK instance is exposed for advanced use cases.
+The underlying client instance is exposed for advanced use cases.
 
 ```typescript
-// Access the PocketBase client directly
+// Access the internal client directly
 const health = await pb.pb.health.check()
 
 // Custom API endpoint
@@ -299,4 +332,4 @@ result.items[0].title  // string — fully typed!
 | `pb.collection(name)` | `PicoBaseCollection` | CRUD operations on a collection |
 | `pb.realtime` | `PicoBaseRealtime` | Realtime subscriptions |
 | `pb.storage` | `PicoBaseStorage` | File URLs and tokens |
-| `pb.pb` | `PocketBase` | Underlying PocketBase SDK instance |
+| `pb.pb` | `PocketBase` | Underlying internal client instance |

package/dist/index.d.mts

@@ -57,6 +57,33 @@ interface FileOptions {
     token?: string;
     download?: boolean;
 }
+type CollectionType = 'base' | 'auth' | 'view';
+interface CollectionModel {
+    id: string;
+    created: string;
+    updated: string;
+    name: string;
+    type: CollectionType;
+    system: boolean;
+    schema: SchemaField[];
+    indexes: string[];
+    listRule: string | null;
+    viewRule: string | null;
+    createRule: string | null;
+    updateRule: string | null;
+    deleteRule: string | null;
+    options: Record<string, unknown>;
+}
+interface SchemaField {
+    system: boolean;
+    id: string;
+    name: string;
+    type: string;
+    required: boolean;
+    presentable: boolean;
+    unique: boolean;
+    options: Record<string, unknown>;
+}
 
 /**
  * Auth module — handles user sign-up, sign-in, OAuth, and session management.
@@ -384,6 +411,31 @@ declare class PicoBaseStorage {
     getFileToken(): Promise<string>;
 }
 
+declare class PicoBaseAdmin {
+    private pb;
+    constructor(pb: PocketBase);
+    /**
+     * Fetch a list of all collections.
+     */
+    listCollections(): Promise<CollectionModel[]>;
+    /**
+     * Fetch a single collection by ID or name.
+     */
+    getCollection(idOrName: string): Promise<CollectionModel>;
+    /**
+     * Create a new collection.
+     */
+    createCollection(data: Partial<CollectionModel>): Promise<CollectionModel>;
+    /**
+     * Update an existing collection.
+     */
+    updateCollection(idOrName: string, data: Partial<CollectionModel>): Promise<CollectionModel>;
+    /**
+     * Delete a collection.
+     */
+    deleteCollection(idOrName: string): Promise<boolean>;
+}
+
 declare class PicoBaseClient {
     /** The underlying PocketBase SDK instance. Exposed for advanced usage. */
     readonly pb: PocketBase;
@@ -393,6 +445,8 @@ declare class PicoBaseClient {
     readonly realtime: PicoBaseRealtime;
     /** Storage module — get file URLs and tokens. */
     readonly storage: PicoBaseStorage;
+    /** Admin module — manage collections (requires admin API key). */
+    readonly admin: PicoBaseAdmin;
     private readonly apiKey;
     private readonly options;
     constructor(url: string, apiKey: string, options?: PicoBaseClientOptions);
@@ -548,4 +602,4 @@ declare class RpcError extends PicoBaseError {
     constructor(functionName: string, status: number, details?: unknown);
 }
 
-export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, CollectionNotFoundError, ConfigurationError, type FileOptions, InstanceUnavailableError, type ListOptions, type OAuthSignInOptions, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, RecordNotFoundError, type RecordQueryOptions, RequestError, RpcError, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };
+export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, CollectionNotFoundError, ConfigurationError, type FileOptions, InstanceUnavailableError, type ListOptions, type OAuthSignInOptions, PicoBaseAdmin, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, RecordNotFoundError, type RecordQueryOptions, RequestError, RpcError, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };

package/dist/index.d.ts

@@ -57,6 +57,33 @@ interface FileOptions {
     token?: string;
     download?: boolean;
 }
+type CollectionType = 'base' | 'auth' | 'view';
+interface CollectionModel {
+    id: string;
+    created: string;
+    updated: string;
+    name: string;
+    type: CollectionType;
+    system: boolean;
+    schema: SchemaField[];
+    indexes: string[];
+    listRule: string | null;
+    viewRule: string | null;
+    createRule: string | null;
+    updateRule: string | null;
+    deleteRule: string | null;
+    options: Record<string, unknown>;
+}
+interface SchemaField {
+    system: boolean;
+    id: string;
+    name: string;
+    type: string;
+    required: boolean;
+    presentable: boolean;
+    unique: boolean;
+    options: Record<string, unknown>;
+}
 
 /**
  * Auth module — handles user sign-up, sign-in, OAuth, and session management.
@@ -384,6 +411,31 @@ declare class PicoBaseStorage {
     getFileToken(): Promise<string>;
 }
 
+declare class PicoBaseAdmin {
+    private pb;
+    constructor(pb: PocketBase);
+    /**
+     * Fetch a list of all collections.
+     */
+    listCollections(): Promise<CollectionModel[]>;
+    /**
+     * Fetch a single collection by ID or name.
+     */
+    getCollection(idOrName: string): Promise<CollectionModel>;
+    /**
+     * Create a new collection.
+     */
+    createCollection(data: Partial<CollectionModel>): Promise<CollectionModel>;
+    /**
+     * Update an existing collection.
+     */
+    updateCollection(idOrName: string, data: Partial<CollectionModel>): Promise<CollectionModel>;
+    /**
+     * Delete a collection.
+     */
+    deleteCollection(idOrName: string): Promise<boolean>;
+}
+
 declare class PicoBaseClient {
     /** The underlying PocketBase SDK instance. Exposed for advanced usage. */
     readonly pb: PocketBase;
@@ -393,6 +445,8 @@ declare class PicoBaseClient {
     readonly realtime: PicoBaseRealtime;
     /** Storage module — get file URLs and tokens. */
     readonly storage: PicoBaseStorage;
+    /** Admin module — manage collections (requires admin API key). */
+    readonly admin: PicoBaseAdmin;
     private readonly apiKey;
     private readonly options;
     constructor(url: string, apiKey: string, options?: PicoBaseClientOptions);
@@ -548,4 +602,4 @@ declare class RpcError extends PicoBaseError {
     constructor(functionName: string, status: number, details?: unknown);
 }
 
-export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, CollectionNotFoundError, ConfigurationError, type FileOptions, InstanceUnavailableError, type ListOptions, type OAuthSignInOptions, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, RecordNotFoundError, type RecordQueryOptions, RequestError, RpcError, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };
+export { type AuthEvent, type AuthResponse, type AuthStateChange, type AuthStateChangeCallback, AuthorizationError, CollectionNotFoundError, ConfigurationError, type FileOptions, InstanceUnavailableError, type ListOptions, type OAuthSignInOptions, PicoBaseAdmin, PicoBaseAuth, PicoBaseClient, type PicoBaseClientOptions, PicoBaseCollection, PicoBaseError, PicoBaseRealtime, PicoBaseStorage, type RealtimeAction, type RealtimeCallback, RecordNotFoundError, type RecordQueryOptions, RequestError, RpcError, type SignInOptions, type SignUpOptions, type UnsubscribeFunc, createClient };