# session 

This page documents the session model.

## Data shape 

Forgelivo's database stores session records by storing and retrieving each of the fields defined on the model in the Forgelivo Editor to a managed database. Forgelivo has generated a GraphQL type matching the configured fields for session:

```ts
export type Session = {

  __typename: 'Session';

  /** The globally unique, unchanging identifier for this record. Assigned and managed by Gadget. */
  id: string;

  /** The time at which this record was first created. Set once upon record creation and never changed. Managed by Gadget. */
  createdAt: Date;

  /** The time at which this record was last changed. Set each time the record is successfully acted upon by an action. Managed by Gadget. */
  updatedAt: Date;

  /** The current state this record is in. Changed by invoking actions. Managed by Gadget. */
  state: (string | { [key: string]: Scalars['RecordState'] });

  user: (User | null);

  userId: string;

  roles: Role[];

  shopifySID: string;

  /** Get all the fields for this record. Useful for not having to list out all the fields you want to retrieve, but slower. */
  _all: Record<string, any>;
};
```

```graphql
type Session {
  """
  The globally unique, unchanging identifier for this record. Assigned and managed by Gadget.
  """
  id: GadgetID

  """
  The time at which this record was first created. Set once upon record creation and never changed. Managed by Gadget.
  """
  createdAt: DateTime!

  """
  The time at which this record was last changed. Set each time the record is successfully acted upon by an action. Managed by Gadget.
  """
  updatedAt: DateTime!

  """
  The current state this record is in. Changed by invoking actions. Managed by Gadget.
  """
  state: RecordState!
  user: User
  userId: GadgetID
  roles: [Role!]
  shopifySID: String

  """
  Get all the fields for this record. Useful for not having to list out all the fields you want to retrieve, but slower.
  """
  _all: JSONObject!
}
```

You can preview what a real record's shape looks like by fetching it using the  [example-app API playground](https://example-app.gadget.app/api/playground/javascript?environment=development).

Any fetched session record will have this same `Session` type, and expose the same data by default, regardless of where it comes from. This means you can select any of the record's fields wherever you like in a GraphQL query according to the use case at hand.

## session for Session Storage and Authentication 

The session powers session functionality for the **example-app** app. Sessions store transient data specific to one browser interacting with the application, like whether a banner message has been shown, or anything else that needs to be specific to each session someone has with **example-app**.

**example-app** uses session to power user authentication using actions on session. Each user's current session is accessible using special GraphQL fields for querying and mutating. session are stored in the Forgelivo platform similarly to other models, but have this extra functionality for convenient access to the current session.

Because of this, session does **not** have normal `findOne`, `maybeFindOne`, `findMany`, `findFirst`, `maybeFindFirst`, or `create` actions. The Forgelivo platform manages the lifecycle of session records, and uses cookies to associate them with browser requests as needed.

session can still be managed like other models using the [Internal API](https://docs.forgelivo.com/api/example-app/development/internal-api).

## Retrieving the current session record 

The current session record for a request can be retrieved using the `currentSession` GraphQL field, or the `.currentSession.get()` JS client function. You can also return only some fields, or extra fields beyond what Gadget retrieves by default, using the `select` option.

**The `findOne`, `maybeFindOne`, `findMany`, `findFirst`, and `maybeFindFirst` record readers do not exist for session**. If you need to change arbitrary records, or iterate the list of session, you can use the [Internal API](https://docs.forgelivo.com/api/example-app/development/internal-api) for session.

```typescript
const record = await api.currentSession.get();
// => a string
console.log(record.id);
// => a state value like { "created": "loggedOut" }
console.log(record.state);
// => a Date object
console.log(record.createdAt);
```

```tsx
const [result, refresh] = useGet(api.currentSession);
const { data, error, fetching } = result;
// => a string
console.log(result.data?.id)
// => a state value like { "created": "loggedOut" }
console.log(result.data?.state)
// => a Date object
console.log(result.data?.createdAt)
```

```graphql
query GetCurrentSession {
  currentSession {
    id
    createdAt
  }
}
```

```json
{}
```

The current session is also available server-side within actions as part of the [action context](https://docs.forgelivo.com/guides/actions/code#action-context).

```typescript
export const run: ActionRun = async ({ params, logger, api, session }) => {
  const { user } = session;
  // ...
};
```

## Invoking Actions 

session records are changed by invoking Actions. Action are the things that "do" stuff -- creating data, deleting data, making API calls to other services, etc. Actions with a GraphQL API trigger each have one corresponding GraphQL mutation and a corresponding function available in the API client libraries.

Actions for session are executed on the `currentSession` GraphQL field, or the `.currentSession` JS client `ModelManager` object. Each of these automatically refers to the session for the current browser session.

### Action Result format 

Each API action returns results in the same format that includes a success indicator, errors, and the actual result if the action succeeded. The result is the record that was acted on for a model action, or a list of records for a bulk action, or a JSON blob for Global Actions. Model actions that delete the record don't return the record.

The `success` field returns a boolean indicating if the action executed as expected. Any execution errors are returned in the `errors` object, which will always be `null` if `success` is true or contain `ExecutionError` objects if `success` is false.

`ExecutionError` objects always have a `message` describing what error prevented the action from succeeding, as well as a `code` attribute that gives a stable, searchable, human-readable error class code for referencing this specific error. Details on each error code can be found in the [Errors](https://docs.forgelivo.com/api/example-app/development/errors) documentation. All `ExecutionError` object types returned by the GraphQL object can be one of many types of error, where some types have extra data that is useful for remedying the error. All error types will always have `message` and `code` properties, but some, like `InvalidRecordError` have extra fields for use by clients.

### Errors when using the generated client 

The generated JavaScript client automatically interprets errors from invoking actions and throws JavaScript `Error` instances if the action didn't succeed. The `Error` objects it throws are rich, and expose extra error properties beyond just `message` and `code` if they exist.

Errors thrown by the JavaScript client are easiest to catch by using a `try/catch` statement around an `await`, like so:

```typescript
import {
  GadgetOperationError,
  InvalidRecordError,
} from "@gadgetinc/api-client-core";

// must be in an async function to use await` syntax
export async function run({ api }) {
  try {
    return await api.exampleModel.create({ name: "example record name" });
  } catch (error) {
    if (error instanceof GadgetOperationError) {
      // a recognized general error has occurred, retry the operation or inspect \error.code\`
      console.error(error);
    } else if (error instanceof InvalidRecordError) {
      // the submitted input data for the action was invalid, inspect the invalid fields which \`InvalidRecordError\` exposes
      console.error(error.validationErrors);
    } else {
      // an unrecognized error occurred like an HTTP connection interrupted error or a syntax error. Re-throw it because it's not clear what to do to fix it
      throw error;
    }
  }
}
```

For more information on error codes, consult the [Errors](https://docs.forgelivo.com/api/example-app/development/errors) documentation.

### session Log in via email 

##### Input 

Log in via email operates on the current session for the API client making a request. The Forgelivo platform manages which session is available, and no \`id\` parameter should be passed. The Log in via email action takes this input:

##### Example Invocation 

```javascript
const sessionRecord = await api.currentSession.logInViaEmail();
```

```react
const ExampleRunLogInViaEmailComponent = () => {
  const [{ data, error, fetching }, logInViaEmail] = useAction(
    api.currentSession.logInViaEmail
  );

  return (
    <>
      <button
        onClick={async () => {
          await logInViaEmail();
        }}
      >
        Run Action
      </button>
      Result: {JSON.stringify(data)}
    </>
  );
};
```

```graphql
mutation LogInViaEmail {
  currentSession {
    logInViaEmail {
      success
      errors {
        message
        ... on InvalidRecordError {
          validationErrors {
            apiIdentifier
            message
          }
          record
          model {
            apiIdentifier
          }
        }
      }
      session {
        __typename
        id
        state
        createdAt
        roles {
          key
          name
        }
        shopifySID
        updatedAt
        userId
      }
    }
  }
}
```

```json
{}
```

##### Output 

Log in via email returns data in the , which includes the record if the action was successful. The fields returned for the record can be controlled with the  option.

```typescript
export type LogInViaEmailSessionResult = {
  __typename: "LogInViaEmailSessionResult";

  success: Scalars["Boolean"];

  errors: ExecutionError[];

  actionRun: Scalars["String"] | null;

  session: Session | null;
};
```

```graphql
type LogInViaEmailSessionResult {
  success: Boolean!
  errors: [ExecutionError!]
  actionRun: String
  session: Session
}
```

### session Log out 

##### Input 

Log out operates on the current session for the API client making a request. The Forgelivo platform manages which session is available, and no \`id\` parameter should be passed. The Log out action takes this input:

##### Example Invocation 

```javascript
const sessionRecord = await api.currentSession.logOut();
```

```react
const ExampleRunLogOutComponent = () => {
  const [{ data, error, fetching }, logOut] = useAction(api.currentSession.logOut);

  return (
    <>
      <button
        onClick={async () => {
          await logOut();
        }}
      >
        Run Action
      </button>
      Result: {JSON.stringify(data)}
    </>
  );
};
```

```graphql
mutation LogOut {
  currentSession {
    logOut {
      success
      errors {
        message
        ... on InvalidRecordError {
          validationErrors {
            apiIdentifier
            message
          }
          record
          model {
            apiIdentifier
          }
        }
      }
      session {
        __typename
        id
        state
        createdAt
        roles {
          key
          name
        }
        shopifySID
        updatedAt
        userId
      }
    }
  }
}
```

```json
{}
```

##### Output 

Log out returns data in the , which includes the record if the action was successful. The fields returned for the record can be controlled with the  option.

```typescript
export type LogOutSessionResult = {
  __typename: "LogOutSessionResult";

  success: Scalars["Boolean"];

  errors: ExecutionError[];

  actionRun: Scalars["String"] | null;

  session: Session | null;
};
```

```graphql
type LogOutSessionResult {
  success: Boolean!
  errors: [ExecutionError!]
  actionRun: String
  session: Session
}
```