orrin-sdk 0.0.16

SDK for creating and registering custom Orrin apps

Orrin SDK v0.0.16

The Orrin SDK v0.x.x series represents the initial iterations of the Orrin SDK. It brings forth a simple Python decorator for developers creating small-scale apps to be deployed on the Orrin platform.

Orrin SDK serves as the bridge between backend logic and UI manipulation.

Architecture: Why Python & Node.js?

The Orrin stack utilizes a hybrid approach for maximum efficiency and flexibility:

• Python (Backend): Used for its simplicity and broad compatibility.
• Node.js (Frontend): Used for flexibility and compatibility with the Orrin Web platform, which is also based on Node.js. Sustaining a unified stack for the web platform ensures seamless integration.

---

Orrin SDK Actions

The current version offers a primary decorator: action. This is placed on top of any function intended to be used by your frontend code to perform activities or manipulate the UI.

Signature

@action(name: str, required_payload: list = [], extra_metadata: dict = {})

Arguments

Argument	Type	Description
name	str	Required. This must explicitly match the function name.
required_payload	list	A list of dictionaries defining arguments passed to the function.
extra_metadata	dict	Optional dictionary for additional context.

1. The name Argument

When uploading the backend, the server stores a copy of the code (excluding SDK configurations) and maps actions to specific functions using this name.

Warning: The name in the decorator must match the function definition exactly. If there is a mismatch, the server will throw a 500 Internal Error when the frontend attempts to call the action, as it will fail to locate the entry point.

2. The required_payload Argument

If your function requires arguments, you must specify them here. This is an array of dictionaries containing the argument's name and expected type.

Structure:

{
    "name": "<argument_name>",
    "type": "<argument_type>"
}

• <argument_name>: The literal argument name used in the Python function.
• <argument_type>: The required Python type (e.g., int, str).
  • Note: You may set the type to "any" if the argument is not restricted to a specific type.

Example Payload: For a function def my_func(arg: int):, the payload configuration would be:

[{"name": "arg", "type": "int"}]

---

Implementation Example

Below is a complete example of the SDK in action.

from sdk import OrrinSDK

# Initialize the SDK
orrin_sdk = OrrinSDK(
    developer_api_key='<your_developer_api_key>',   # Required
    app_name='ATestApp',                            # Required
    desc='A test app built for the Orrin platform!' # Required metadata
)

# Standard helper function (Not accessible directly by UI)
def lol():
    return 'You can use non-action based functions inside action-based functions!'

# Action function (Accessible by UI)
@orrin_sdk.action('test', required_payload=[{"name": "a", "type": "any"}])
def test(a):
    return {'message': f'test done! {a}'}

# Finalizes configuration and requests app backend creation
orrin_sdk.finalize()

Important Implementation Notes:

1. Do not forget .finalize(): This must be called at the end of your script.
2. Naming Conventions: App names must not contain spaces. The server will reject backend uploads if the app name violates this rule.

Using the Action in UI

Once deployed, you can utilize this action via the Node.js-based frontend SDK. The result returned from the Python function (test) can be used to determine how to manipulate your UI.

---

Extra Metadata

An elaborate developer platform is in development to provide direct access to data regarding your apps. To support this, you may need to attach additional metadata to your actions, particularly as your backend grows.

Note: Please keep apps small-scale; Orrin is not intended for massive social media clones.

Example with Metadata:

from sdk import OrrinSDK

orrin_sdk = OrrinSDK(
    developer_api_key='<your_developer_api_key>',
    app_name='ATestApp',
    desc='A test app built for the Orrin platform!'
)

@orrin_sdk.action(
    'test',
    required_payload=[{"name": "a", "type": "any"}],
    # Add any dictionary data here to help you understand the action later
    extra_metadata={'reason': 'This action is a test. Do not use in production!'}
)
def test(a):
    return {'message': f'test done! {a}'}

orrin_sdk.finalize()

There is no limit or schema requirement for extra_metadata. Use it as needed to document your code.

---

Registration and Deployment

1. Run Your Script

You must run your Python script locally to register the actions and upload the backend code.

• If you have no functions decorated with @action, your codebase is considered "dead" (unusable on the platform).
• Such submissions will be marked as DENIED upon review, and you will be required to resubmit with correct configurations.

2. Review Process

After .finalize() runs:

• Your backend status becomes PENDING.
• The review process can take up to 3 days.
• Final states are either AUTHORIZED or DENIED.

For more details, refer to: https://stellr-company.com/orrin/sdk

---

App Status & Policy

When you submit a backend, an application is created on the server.

• Dependencies: A frontend cannot exist without an associated backend.
• Review: The app undergoes a full review only after both backend and frontend are submitted.

Policy Enforcement

If an app is found to be deceptive, abusive, discriminatory, or in violation of any Stellr company policy:

1. It will be removed from the review queue.
2. It will be archived.
3. Archived applications cannot be resubmitted.

Warning: Attempting to bypass enforcement by re-uploading an archived application under a different name may result in the revocation of your developer API key and loss of platform access.

Status Lifecycle

There are 4 possible statuses for an application:

1. NOT_LIVE
2. IN_REVIEW
3. LIVE
4. DELETED

Transitions:

• Submission: When Stellr begins reviewing your app, the status updates to IN_REVIEW.
• Rejection/Issues: If issues require attention, the status reverts to NOT_LIVE.
• Approval: Upon approval, the status updates to LIVE.
• Marketplace Removal: You may voluntarily switch an app from LIVE to NOT_LIVE to remove it from the public marketplace.

Note: Switching an app from LIVE back to NOT_LIVE may subject the app to a new review process before it can go live again.

---

New versions of Orrin SDK are in the works.

Please see https://stellr-company.com/orrin/sdk/license for the Proprietary License for this package.