fix: ensure y-websocket is default provider in sdks (#2535)

Author: harbournick

apps/cli/src/commands/open.ts

@@ -1,5 +1,9 @@
 import { getBooleanOption, getNumberOption, getStringOption, resolveDocArg, resolveJsonInput } from '../lib/args';
-import { parseCollaborationInput, resolveCollaborationProfile } from '../lib/collaboration';
+import {
+  buildShorthandCollaborationInput,
+  parseCollaborationInput,
+  resolveCollaborationProfile,
+} from '../lib/collaboration';
 import {
   getProjectRoot,
   createInitialContextMetadata,
@@ -105,12 +109,11 @@ export async function runOpen(tokens: string[], context: CommandContext): Promis
       payload.bootstrapSettlingMs = bootstrapSettlingMs;
     collaborationInput = parseCollaborationInput(payload);
   } else if (collabUrl) {
-    collaborationInput = parseCollaborationInput({
-      providerType: 'hocuspocus',
+    collaborationInput = buildShorthandCollaborationInput({
       url: collabUrl,
       documentId: collabDocumentId,
-      ...(onMissing != null ? { onMissing } : {}),
-      ...(bootstrapSettlingMs != null ? { bootstrapSettlingMs } : {}),
+      onMissing,
+      bootstrapSettlingMs,
     });
   } else if (collabDocumentId) {
     throw new CliError('MISSING_REQUIRED', 'open: --collab-document-id requires --collab-url.');

apps/cli/src/lib/__tests__/collaboration.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  buildShorthandCollaborationInput,
+  DEFAULT_SHORTHAND_COLLABORATION_PROVIDER_TYPE,
+  parseCollaborationInput,
+  resolveCollaborationProfile,
+} from '../collaboration';
+
+describe('buildShorthandCollaborationInput', () => {
+  test('uses y-websocket as the default provider type', () => {
+    expect(DEFAULT_SHORTHAND_COLLABORATION_PROVIDER_TYPE).toBe('y-websocket');
+  });
+
+  test('returns a validated CollaborationInput with all params', () => {
+    const input = buildShorthandCollaborationInput({
+      url: 'ws://localhost:4000',
+      documentId: 'my-doc-room',
+      onMissing: 'error',
+      bootstrapSettlingMs: 2000,
+    });
+
+    expect(input).toEqual({
+      providerType: 'y-websocket',
+      url: 'ws://localhost:4000',
+      documentId: 'my-doc-room',
+      onMissing: 'error',
+      bootstrapSettlingMs: 2000,
+    });
+  });
+
+  test('handles minimal params (url-only)', () => {
+    const input = buildShorthandCollaborationInput({ url: 'ws://localhost:4000' });
+
+    expect(input.providerType).toBe('y-websocket');
+    expect(input.url).toBe('ws://localhost:4000');
+    expect(input.documentId).toBeUndefined();
+    expect(input.onMissing).toBeUndefined();
+    expect(input.bootstrapSettlingMs).toBeUndefined();
+  });
+
+  test('flows through to resolveCollaborationProfile with correct provider', () => {
+    const input = buildShorthandCollaborationInput({
+      url: 'ws://localhost:4000',
+      documentId: 'my-doc-room',
+    });
+    const profile = resolveCollaborationProfile(input, 'fallback-session');
+
+    expect(profile.providerType).toBe('y-websocket');
+    expect(profile.documentId).toBe('my-doc-room');
+  });
+});
+
+describe('parseCollaborationInput', () => {
+  test('accepts explicit hocuspocus provider type', () => {
+    const input = parseCollaborationInput({
+      providerType: 'hocuspocus',
+      url: 'ws://localhost:1234',
+      documentId: 'room-1',
+    });
+
+    expect(input.providerType).toBe('hocuspocus');
+  });
+});

apps/cli/src/lib/collaboration.ts

@@ -43,6 +43,7 @@ export type CollaborationRuntime = {
   dispose(): void;
 };
 
+export const DEFAULT_SHORTHAND_COLLABORATION_PROVIDER_TYPE: CollaborationProviderType = 'y-websocket';
 const DEFAULT_SYNC_TIMEOUT_MS = 10_000;
 const SYNC_POLL_INTERVAL_MS = 25;
 const ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -140,6 +141,18 @@ export function resolveCollaborationProfile(input: CollaborationInput, sessionId
   };
 }
 
+export function buildShorthandCollaborationInput(params: {
+  url: string;
+  documentId?: string;
+  onMissing?: string;
+  bootstrapSettlingMs?: number;
+}): CollaborationInput {
+  return parseCollaborationInput({
+    providerType: DEFAULT_SHORTHAND_COLLABORATION_PROVIDER_TYPE,
+    ...params,
+  });
+}
+
 export function resolveCollaborationToken(profile: CollaborationProfile): string | undefined {
   if (!profile.tokenEnv) return undefined;
   const token = process.env[profile.tokenEnv];

apps/docs/document-engine/sdks.mdx

@@ -204,6 +204,11 @@ Use this when your app already has a live collaboration room (Liveblocks, Hocusp
 
 Pass `collabUrl` and `collabDocumentId` to `client.open`:
 
+<Note>
+  The `collabUrl` + `collabDocumentId` shorthand defaults to the `y-websocket` provider. To connect to a
+  Hocuspocus server, pass an explicit `collaboration` object with `providerType: 'hocuspocus'`.
+</Note>
+
 <Tabs>
   <Tab title="Node.js">
     ```typescript
@@ -248,6 +253,35 @@ Pass `collabUrl` and `collabDocumentId` to `client.open`:
   </Tab>
 </Tabs>
 
+### Connect to Hocuspocus explicitly
+
+Use the explicit `collaboration` object when your server speaks the Hocuspocus protocol instead of `y-websocket`:
+
+<Tabs>
+  <Tab title="Node.js">
+    ```typescript
+    const doc = await client.open({
+      collaboration: {
+        providerType: 'hocuspocus',
+        url: 'ws://localhost:1234',
+        documentId: 'my-doc-room',
+      },
+    });
+    ```
+  </Tab>
+  <Tab title="Python">
+    ```python
+    doc = await client.open({
+        "collaboration": {
+            "providerType": "hocuspocus",
+            "url": "ws://localhost:1234",
+            "documentId": "my-doc-room",
+        }
+    })
+    ```
+  </Tab>
+</Tabs>
+
 ### Start an empty room from a local `.docx`
 
 If the room is empty, pass `doc` together with collaboration params:
@@ -285,7 +319,7 @@ What happens when you pass `doc`:
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `collabUrl` | `string` | — | WebSocket URL for your collaboration provider. |
+| `collabUrl` | `string` | — | WebSocket URL for your collaboration provider. Shorthand defaults to `y-websocket`. |
 | `collabDocumentId` | `string` | session ID | Room/document ID on the provider. |
 | `doc` | `string` | — | Local `.docx` used only when the room is empty. |
 | `onMissing` | `string` | `seedFromDoc` | `seedFromDoc`, `blank`, or `error`. |

packages/sdk/langs/python/README.md

@@ -153,6 +153,8 @@ Use this when your app already has a live collaboration room (Liveblocks, Hocusp
 
 Pass `collabUrl` and `collabDocumentId` to `client.open`:
 
+> The `collabUrl` + `collabDocumentId` shorthand defaults to the `y-websocket` provider. To connect to a Hocuspocus server, pass an explicit `collaboration` object with `providerType: "hocuspocus"`.
+
 ```python
 import asyncio
 
@@ -175,6 +177,20 @@ async def main():
 asyncio.run(main())
 ```
 
+### Connect to Hocuspocus explicitly
+
+Use the explicit `collaboration` object when your server speaks the Hocuspocus protocol instead of `y-websocket`:
+
+```python
+doc = await client.open({
+    "collaboration": {
+        "providerType": "hocuspocus",
+        "url": "ws://localhost:1234",
+        "documentId": "my-doc-room",
+    }
+})
+```
+
 ### Start an empty room from a local `.docx`
 
 If the room is empty, pass `doc` together with collaboration params:
@@ -199,7 +215,7 @@ What happens when you pass `doc`:
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `collabUrl` | `string` | — | WebSocket URL for your collaboration provider. |
+| `collabUrl` | `string` | — | WebSocket URL for your collaboration provider. Shorthand defaults to `y-websocket`. |
 | `collabDocumentId` | `string` | session ID | Room/document ID on the provider. |
 | `doc` | `string` | — | Local `.docx` used only when the room is empty. |
 | `onMissing` | `string` | `seedFromDoc` | `seedFromDoc`, `blank`, or `error`. |