ccs-react-native

React Native compatible CCS/Freeschema core package.

This package intentionally excludes browser-only pieces from mftsccs-browser: widgets, DOM rendering, service workers, BroadcastChannel, and IndexedDB.

Install From Local Folder

npm install ../react-package-ccs

Install from npm

npm install ccs-react-native

Configure

import AsyncStorage from "@react-native-async-storage/async-storage";
import {
  init,
  LoginToBackend,
  LocalTransaction,
  FreeschemaQuery,
  FreeschemaQueryApi,
} from "ccs-react-native";

await init({
  baseUrl: "https://your-csharp-api.example.com",
  nodeUrl: "https://your-node-api.example.com",
  applicationName: "your-app",
  storage: AsyncStorage,
  ccsConfig: {
    videoUrl: "https://video.freeschema.com",
    videoApiKey: "your-video-api-key",
  },
});

const login = await LoginToBackend("[email protected]", "password");

storage is optional. Without it, local concepts/connections work in memory for the current app session. With a React Native storage adapter, pending local data and profile metadata can survive restarts.

Asynchronous Initialization in React Native (useEffect)

Because initialization (init) is asynchronous (it hydrates local state and tokens from storage), you should initialize it within a root-level useEffect hook and defer rendering your main components until it is ready:

import React, { useEffect, useState } from 'react';
import { ThemeProvider } from 'react-navigation';
import { init } from 'ccs-react-native';
import AppTabs from './components/app-tabs';

export default function AppLayout() {
  const [isCcsReady, setIsCcsReady] = useState(false);

  useEffect(() => {
    async function initializeCCS() {
      try {
        await init({
          baseUrl: process.env.EXPO_PUBLIC_BASE_URL || 'https://api.example.com',
          nodeUrl: process.env.EXPO_PUBLIC_NODE_URL || 'https://node.example.com',
          applicationName: process.env.EXPO_PUBLIC_APP_NAME || 'my-app',
        });
      } catch (error) {
        console.error('Failed to initialize ccs-react-native:', error);
      } finally {
        setIsCcsReady(true);
      }
    }

    initializeCCS();
  }, []);

  if (!isCcsReady) {
    return <SplashOverlay />; // Or loading spinner
  }

  return <AppTabs />;
}

Why is this pattern used?

1. Prevents Race Conditions: Querying or storing concepts/connections before the local state is fully hydrated will result in reading stale/empty values or calling unauthorized backend endpoints.
2. Loads Cached Authentication: The init function hydrates saved user profiles and tokens from persistent storage so that the session can be restored before making backend calls.
3. Ensures Thread Safety: React Native uses asynchronous native modules for storage. Blocking the rendering tree guarantees that components trying to interact with the connection system on mount will have the necessary state available immediately.

Local Concepts And Connections

const transaction = new LocalTransaction();
await transaction.initialize();

const person = await transaction.MakeTheInstanceConceptLocal(
  "the_person",
  "Alice",
  true,
  101,
  4
);

const email = await transaction.MakeTheInstanceConceptLocal(
  "the_email",
  "[email protected]",
  false,
  101,
  4
);

await transaction.CreateConnection(person, email, "the_person_email");
await transaction.commitTransaction();

Included Core APIs

• MakeTheInstanceConceptLocal
• MakeTheTypeConceptLocal
• CreateTheConceptLocal
• CreateTheConnectionLocal
• CreateConnection
• CreateConnectionBetweenTwoConceptsLocal
• LocalTransaction
• GetTheConcept
• GetConceptBulk / get_concept_bulk
• GetConnectionBulk / get_connection_bulk
• GetConceptByCharacter
• GetConceptByCharacterValue
• GetConceptByCharacterAndType
• LoginToBackend
• Signin
• Signup
• SignupEntity
• FreeschemaQuery
• FreeschemaQueryApi
• uploadAttachment
• getVideoPlaybackUrl
• uploadImage
• uploadImageV2
• uploadR2Storage
• getR2PresignedUploadUrl
• uploadToR2PresignedUrl
• uploadWithR2PresignedUrl
• uploadFile
• getUploadFileLimit
• GetImageApi
• GetFreeschemaImage
• GetFreeschemaImageUrl

Uploading Files & Caching Images

This package provides helper functions to handle file/image uploading and CDN image caching.

File/Image Uploading

import { uploadAttachment } from "ccs-react-native";

// In React Native, obtain file metadata from a picker (e.g. expo-document-picker)
const file = {
  uri: "file://path/to/image.jpg",
  name: "profile.jpg",
  type: "image/jpeg"
};

const res = await uploadAttachment(file);
if (res.success) {
  console.log("Uploaded URL:", res.url);
}

uploadAttachment and uploadImage now use the pre-signed R2 workflow. uploadAttachment accepts a file object directly and returns the public URL. uploadImage keeps the existing FormData signature and reads the image from either the file key or the legacy image key.

import { uploadImage } from "ccs-react-native";

const formData = new FormData();
formData.append("image", file, file.name);

const response = await uploadImage(formData);
console.log(response.url);

For direct R2 uploads without a pre-signed URL, append the file under the file key and call uploadR2Storage or uploadFile.

import { uploadR2Storage } from "ccs-react-native";

const formData = new FormData();
formData.append("file", file, file.name);

const response = await uploadR2Storage(formData);
console.log(response?.data?.url);

For the pre-signed R2 workflow, use uploadWithR2PresignedUrl to create the URL and upload the file with one call. The returned url is the public CDN URL.

import { uploadWithR2PresignedUrl } from "ccs-react-native";

const response = await uploadWithR2PresignedUrl(file, {
  fileName: "photo.png",
  contentType: "image/png",
  folder: "",
  expiresInSeconds: 900,
});

console.log(response.url);

Video uploads now trigger transcoding automatically after a successful upload. The package keeps the normal upload flow, then calls POST /videos/process on your configured videoUrl using the successful upload response's data.key as the filePath.

const response = await uploadWithR2PresignedUrl(file, {
  fileName: "lesson.mp4",
  contentType: "video/mp4",
});

If you're migrating from the older init shape, you can keep baseUrl, nodeUrl, applicationName, and storage at the top level, and put the video-specific runtime settings under ccsConfig.

If you need to skip that follow-up process call for a specific video upload, pass processVideo: false.

const response = await uploadWithR2PresignedUrl(file, {
  fileName: "lesson.mp4",
  contentType: "video/mp4",
  processVideo: false,
});

If you have the original uploaded video URL and want the streamable playback URL when transcoding finishes, call getVideoPlaybackUrl. It returns the HLS playback URL when the video status API reports ready; otherwise it returns the original URL you passed in.

import { getVideoPlaybackUrl } from "ccs-react-native";

const resolvedUrl = await getVideoPlaybackUrl(
  "https://s3cdn.boomconcole.com/boomconsoleall/users/14788/attachments/videos/98263f8d48154563b69bdf23e05b2919.mp4"
);

console.log(resolvedUrl);

You can also call getR2PresignedUploadUrl and uploadToR2PresignedUrl separately if you need manual control over the PUT step.

Media derivative URLs (thumbnail / HLS / small / medium)

Given the original upload URL, deriveMediaUrls builds every derived asset URL (video thumbnail, HLS master playlist, image small/medium) offline — no API call. verifyMediaUrls and verifyMediaAssets confirm against the server once processing finishes. See docs/media-urls.md for the full reference.

import { deriveMediaUrls, verifyMediaUrls } from "ccs-react-native";

const urls = deriveMediaUrls("https://s2cdn.boomconsole.com/users/10267/<fileId>.jpg");
// { kind: "image", original, small, medium, ... }

const status = await verifyMediaUrls(originalVideoUrl);
// { verified, ready, status, urls: { playback, thumbnail, ... }, derived }

CDN Caching for Images

Use GetFreeschemaImageUrl to fetch the optimized, CDN-cached image URL:

import { GetFreeschemaImageUrl } from "ccs-react-native";

// Get standard CDN cached URL
const cachedUrl = GetFreeschemaImageUrl("https://my-backend.com/images/123.jpg");

// Get a smaller thumbnail size version of the CDN cached URL
const smallUrl = GetFreeschemaImageUrl("https://my-backend.com/images/123.jpg", "small");

Not Included

• Widgets and widget rendering
• Browser DOM helpers
• Service worker routing
• IndexedDB caches
• Browser event listeners